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INTRODUCTION 


` This manual describes SDOS 1. 2, a 6800 disk Oberdtino system. 
The manual has several sections: 3 


1) Features 
23) Concepts: being where simple definitions of terms used 
‘throughout: the rest of the manual are given.. 


3) Operator ' s Guide. This describes how to initiate 
execution of application and support programs: in detail. 


SE to user. Sly programs. This. section ^ 
oD -SDOS: “architecture. ‘This section: describes the structure 
of SDOS ,, the 1/0- package and the file system. 


6) I/O package. This section describes the 1/0 See used 
to interface SDOS to EE devices, and how Co modify 


pote. 
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` SDOS FEATURES 


|. SDOS is a 6800 microprocessor-based Disk Operating System 
f which provides many features which ease and simplify the ` 
— es Constructioh and execution of application programs. These 
A “features include: I c L. j E 


` l) Device independence: the ability to treat all devices the 
.Same way. : SÉ y AC. : ° 


2) Named files: users need only remember mnemonics for the 
— Programs they wish to use. : E Beers f Ñ 


————Aatomatic-disk-file management: SDOS allocates and frees’ 

cy diek space automatically as needed by write requests. Space 
des E “Management is dynamic, but optimized for quick access. 

SEET possible... v - wes o ea te e cun m 7 


Di 


^31) Multiple and mixed disk device support: both mini-floppies 
and 60 megabyte storage modules can be attached to the same ` ` 
system running SDOS. ` 


5) Error trapping and automatic reporting: most errors are 
saa printed on the console in English text instead of cryptic 
numbers (A HELP command converts the remaining cryptic 
numbers to English text). Application programs can capture 
and attempt recovery from virtually any error. j 


6) Hashed disk directory with automatic expansion: hashing 

ensures quick look-up of file names; automatic directory 

expansion means that disk space is the only limit to the 
number of files on a disk. 


-7) Sequential and randomly addressable (to the byte) disk 
-files: any file can be processed both sequentially and 
randomly.  Read-ahead improves. performance on sequential 

reads. The SDOS file structure ensures that no more than two 
disk reads are necessary to randomly access a file; buffering 
..in SDOS normally trims this to a single disk read, even for 
.files scattered over the entire disk. 


l 
E 
|: š 
| 


| À command interpreter: a package which contains many 
ES Useful utilities for listing files, copying, etc., is 
automatically loaded when application programs stop running. 


— 9) Latency and spiral tuning: to allow sequential read 
optimization. 
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Lë Many utility programs: to aid initializing, copying, and . 
repairing SDOS disk file systems. SN Dn l 


11) Command files: allow sequences of keyboard commands to be 
"^ stored and later executed. Conditional execution allows 
: recovery from processing errors. e 


12) Easy addition of new peripheral drivers. 


` 13) Interrupt-driven I/O: enhances system throughput. 
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SDOS CONCEPTS 


This section contains a short summary of the concepts | needed. 
to understand SDOS. 


SDOS stands or the Software Dynamics Operating System: “The ` 
operating system is a (set of) computer program(s) which 
makes the raw computer hardware much easier to deal wish, 
both for propio and for other computer programs, 


The term "operating system" actually means two things: in i 
broad sense, it means the entire set of programs needed to 


operate a computer y: not counting the appl ication programs. ee o 


This includes a program that is nearly always resident in the... 
computer that lets other programs conveniently converse with 
peripherals and use the hardware efficiently; it includes a 


^ set of utility programs to help the operator of a computer ee d E 


manage the contents of disks and transfer data between 
peripherals, and it includes program development tools such ` 
as compilers, editors, etc. In a narrower sense (the SDOS 
sense), the operating system means the memory resident. 
program and the utility programs. Sometimes we call the 
memory resident part the "operating system", because the 
utility programs generally use it to perform their functions 
in exactly the same manner as the application programs. 


Computer programs generally manipulate data on "devices". A 
device is a (electromechanical) mechanism for storing, 
acquiring, or outputting data in some fashion; typical 
examples are disks, CRTs, line printers, sensors, etc. 
Devices are given unique names to distinguish them from one 
another. Typical device names are Df:, Dl:, pee LPT: 

CLOCK: y and CONSOLE:. 


A "disk" is a rotating magnetic platter used for storing 
large amounts of data. A "disk drive" is an electronic 
_ mechanism for writing data on a disk; a particular disk drive 
may be used to read or write data on many independent disks 
at different times. The terms "floppy disk" and "disk 
cartridge" are both Nd d: by "disk" throughout: this 

~ document. : EE l SC 


A "file" is a deeg for a logically related, group - now DT. 


of data. It may represent a stream of keystrokes de "ur 
from a keyboard on a CRT, data stored in a section of disk.. 
memory, or a portion of a magnetic tape. Usually, file 
refers to data stored on a disk. . 
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A "file name" is an arbitrary name given to a file of data.. 
Usually, the names of the data files are stored on the same 


devices as the data itself. To specify a particular data 


. file uniquely, a device name and the file name must be given 


together. This combination is also referred to as a "file 
name", Typical file names are: ABC, Dii EE TXT and LPT:. 


A segtensions ie a suffix of a file name that gives the 


operator some jidea of the type of contents of a file. 
Extensions are usually set off from the rest of the file name ` 
by a special character such as ".". Typical extensions might 
be .BAS for. pe program sources, .TXT for raw textual data, 


etc; We 


A "directory" is ee file used to keep track of file names | 


^ and the location of data file contents on a i 


A "bit" is he. smallest unit of luteruation storage possible 


and can only represent the values "off" or "on" (interpreted 
as ð or 1 respectively). A "byte" is a unit of storage 
comprised of 8 bits, and can store the code for a single 
printable Character or a number in the range 0 to 255» 


A "sector" is the minimum amount of data a disk will read or 
write and is usually some power of 2 number of bytes such as 
128 or 256 bytes. 


A "cluster" is the unit of allocation of disk space to files 
(the minimum amount of disk space that SDOS will allocate to 
a file). The size of a cluster is measured in sectors. and 
may be from 1 to 255 sectors. 


A "program" is a set. of instructions for a computer to 


process to carry out some operation (computing, printing, 


sorting, etc.). A "utility" program is one which serves some 
common need of the operator of the computer, süch as a 
program to list data on a printer, erase unwanted. data files, 
etc. A "command interpreter" is a program which executes a 
utility function or causes an application program to be 
executed as à result of operator input. 


SK "driver" is a special computer program that allows an 
“application program to transfer data to and from a device, 

^ and to control that device, without requiring the application 

- program to know a lot of detail about now. to operate the” š 

B device electronics. l : 


Notation used in this manual: Numbers with a prefix Of 
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(:7F) are hexadecimal. In 6800 Assembly code, this. x 
. hexadecimal prefix is shown as "$", consistent with assembler . 
conventions. Numbers without a "s" prefix are decimal. 
Bit numbers correspond to the appropriate power of 2; Lex 
bit. £ corresponds to :@1 and bit 7 corresponds to :80. | 
du U 
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x _SDOS SYSTEM ARCHITECTURE 


This section gives some general. details on the structure of 


-SDOS. | 


First. we describe the philosophy of the file system a SS 


.it is organized; then we discuss the set of programs which 


comprise "SDOS"; finally we 'talk about the structure of the 


 memory- -resident portion of .SDOS. 


Files are a mechanism for storing and te£rieving: data.  SDOS. 


defines a file as a set of data bytes with the first byte 


being numbered Ø, the second being numbered l, etc. Data iso 


moved to and from files in variable-length blocks of 8 bit 


bytes. SDOS allows two methods of file access: sequential 
and random. Sequential access allows blocks of data to be 
—pread/written to/from- successive bytes in the file. Random |... 
. access allows a file to be positioned to a particular byte so 


that sequential I/O may start from that point. In effect, 
SDOS makes a file appear as a huge virtual memory. This... 
technique allows both sequential and random access devices to 
be treated as similarly as sssi thus increasing device 
independence. ; 


The contents of a disk can be treated as simply a random 
access file, or as a set of named disk files, with each named 
disk file having the set of properties described above... SDOS_ 
keeps track of disk file sizes down to the byte, so that what 
a program puts into a disk file is piece! what it gets 


back, no more and no less. 


Disk files can be extended dynamically as needed; SDOS viti 
allocate disk space as needed. No explicit guarantee is made 
that a file occupies a contiguous section of a disk; however, 
SDOS attempts to allocate disk space in a fashion which 
"maximizes" the contiguity of a file. : 


Disk files have names, protection status, and location on à 


particular disk. No disk file may reside partly on one disk 
and partly on another. Each disk has its own DIRECTORY.SYS 
file, which records the names, location, size and other data 


about all the files on that disk.” 


Each diBk has Several files that are used by SDOS in normal ` 
Oper at tone me ZS l 
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= DIRECTORY. SYS- 
M -BOOT.SYS .- a. f 
` DISKMAP.SYS A" EUN ICE 
—8DOS.SYS . .'. WAS ul EU 
ERRORMSGS.SYS .. . de SCH 
BADCLUSTERS.SYS SC? WA 
DEFAULTPROGRAM | jd 


Boor. SYS . is a file that contains a disk identification, disk 


E SYS into Ee 


E DISKMAP. sys is a file that contains one. bit per cluster on 
_ the disk. A "zero" bit indicates that: ‘the corresponding 


^ cluster is available for use in creating or extending a file. ` 


A "one" bit says that the corresponding cluster is already. 
allocated to a file. If DISKMAP.SYS is not present on a. 
disk, no files may be created, extended, or deleted. 


BADCLUSTERS. SYS is the file to which any clusters. that 
contain unreadable or unwriteable (i.e., "bad") data sectors 
are allocated. Bad clusters are marked in DISKMAP. SYS as 
‘allocated so that they will not Be. re- -allocated to other 
files. : : 


ERRORMSGS. sys contains the text equivalent of many error 
codes, and is used to translate the error codes into the text 
form for display to the operator. 


DEFAULTPROGRAM is the (user) program that is utone tically 
executed by SDOS whenever any other user program ee 
operation or is killed by the operator. Normally, i i 
contains a copy of SDOSCOMMANDS, an operator ea ee 
package; for turnkey systems,. it may. contain: an application - 
program. 


SDOS.SYS contains the memory-resident part of the SDOS- 

operating system in SDOS load record format. This file's ` 
..contents are loaded into memory by the. boot procedures: . 
f thereafter, the file is not used. Cha 


|. The programa that comprise SDOS consist of the following; 


SDOS. sys ' l 
SDOSCOMMANDS (DEFAULTPROGRAM) 
. SDOSDISKINIT 


Copyright (C) 1978 Software Dynamics | 
TE 


MCN 


...SDOS USER'S MANUAL | 


SDOSDISKVALIDATE, SDOSDISKVAL.PAS2, SDOSDISKVAL.PAS3 ` 


SDOSDISKVAL.PAS4,. SDOSDISKVAL.PAS5 
SDOSDISKBACKUP 3 vd Pe UI PIS 

ERRORMAINT = - Mw S e E MEINT 

 MAKEBINARY ` uud SSC ae 


Programs perform 1/0 ana other utility operations via System 


Calls (SYSCALLS). Each SYSCALL is a subroutine call to the 


memory resident part of SDOS with a set of parameter data 
.that describes the function to be performed and the data. on 
which the function is. to operate, f 


TER of the functions describes in the section under SYSCALLS | 


are implemented by the memory resident portion of BDOS.SYS. 
The memory resident portion is split into four major parts: 


-SDOS Front End,.SDOS Disk File Driver, SDOS Disk Device UR 
.- Driver, and the 1/0 package. The first three parts together 


are actually SDOS; in many circumstances, we are sloppy and 
refer to the memory resident part as "SDOS", or even to the 
entire implementation (utility programs, philosophy, and 

memory.resident part) as "SDOS". The use. should be obvious 


"from context. 


SDOS Front End ` 


Ree de qm ` fe 
$e tom eae fen 


(SYSCALL Interpretation) 


. Driver 


S ! ic 
! ! 
D L 1 
Disk 1 Disk H 

(8) File ! Device Ne 
d Driver ! 
! ! 
! H 


“C I/O Package os U 


Que Sem $e Ge den $e G (Qe 9 Gee Que ° Qe ° 


Uu 
| í 0m EE gue (es Que D Qe Qu (Qe ç e 


The SDOS Front End intercepts SYSCALLs, does some initial 
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processing, and then acts as a giant switch, sending the 
. SYSCALLs to the appropriate device drivers. The Front End. 
-also contains all the mechanisms that handle jl np s 
taska, etc. I 


The Disk Device and File Drivers are actually integrated with. 
the Front End in the file SDOSSYSddK. HIR, and E the 
file management part of SDOS. : 


The I/O package implements all of the GENEE device drien 
(CONSOLE:, LPT:, CLOCK:, etc.); it contains logical sector. 
I/O) routines for the Disk Device and File Drivers, and it 
insulates SDOS from all of the particular local. hardware 
‘peculiarities. `The I/O package is designed explicitly to’ be 
the place that all user customizing of SDOS is to be 
performed, and nowhere else; the user may not modify SDOS 


proper. Alteration of the I/O package reguires pP EE 


"Sophistication on the pare SE the user. ` 


SDOSCOMMANDS is a user program which acts. as an bberator- 
interface. It converts operator commands into sequences of 
SYSCALLs which perform these operator's requests. ` 
SDOSCOMMANDS recognizes and performs certain commands by 
itself. All other requests to SDOSCOMMANDS are assumed to be 
requests to run a program specified in the DIRECTORY.SYS. 
Usually, a copy of SDOSCOMMANDS has been poena in the Eire. 
DEFAULTPROGRAM. 


SDOSDISKINIT is a user program that takes a freshly formatted: 
disk cartridge and sets it up so SDOS. can write files on it. 
In particular, SDOSDISKINIT constructs the files 
DIRECTORY.SYS, BOOT.SYS, DISKMAP.SYS, and BADCLUSTERS.SYS, on 
the disk; a vestigial SDOS.SYS file is included in case this 
disk will be used as a system disk. : l 


SDOSDISKVALIDATE is a user program that verifies and fixes 
the file structure on a disk; it cannot check to make sure 
the data is correct. If file structure errors are found, 
they are reported and the operator is given a choice on 
methods of fixing the problem. In most cases, the fix 
results in losing some data; not fixing usually leads to 
larger data losses at a later time because of a. for ED Com. 
disaster. SDOSDISKVAL.PAS2, SDOSDISKVAL. PAS3, 
,SDOSDISKVAL. PAS4 -and SDOSDISKVAL. PAS5 are parts of. 
SDOSDISKVALIDATE. 


SDOSDISKBACKUP is a utility to make backup copies of entire 
disks, or subsets of the files on those disks. 
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. ERRORMAINT. is a user program to help the operator maintain ` 
the ERRORMSGS.SYS file. ` HL S VLA S E. u 


 MAKEBINARY converts MIKBUG records into SDOS load format 


records, which considerably Speeds up program loading and 


uses less file space. 


EELER 
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^' -ERRORMSGS.SYS 


SDOS COMPONENTS: ` ` 
. . SYSTEM FILES: 


<o BOOT.SYS 


SDOS.SYS 


-DISKMAP.SYS 


." DIRECTORY. SYS 


“SYSTEM UTILITIES: 


SDOSCOMMANDS 


SDOSDISKINIT 
SDOSDISKVALIDATE 


SDOSDISKBACKUP . 


MAKEBINARY 


 ERRORMAINT. 


DATA FILES: 


SDOSSYSGEN* 


| SDOSUSERDEFS. ASM 


J| $DOSIOPKDEFS. ASM* 
" SDOSIOPACK. ASM* - 
""SDOSSYSdd.MIK* | 


oo 


SDOSBOOT.MIK* 
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. DISK TUNING CONSTANTS & BOOTSTRAP 


PROGRAM 


. MEMORY RESIDENT PORTION OF SDOS 


MAP OF ALLOCATED CLUSTERS 

(1 BIT PER I, 

LIST OF FILES, FILE LOCATIONS, . 
PROTECTIONS, ETC. 

A FILE WHICH CONTAINS ONLY UNUSABLE 


‘CLUSTERS 


ERROR NUMBER TO TEXT 
MESSAGE CONVERSION 


SDOS COMMAND INTERPRETER PROGRAM WITH 


. MANY. SIMPLE BUT USEFUL UTILITIES 


(USUALLY HIDDEN IN DEFAULTPROGRAM) 
PLACES AN SDOS COMPATIBLE FILE 
STRUCTURE ON AN EMPTY DISK i 
VALIDATE AND REPAIR SDOS FILE 


STRUCTURE , 


MAKES BACK BE COPIES OF DISKS OR 
FILES | 

CONVERTS MIKBUG OBJECT TO SDOS 
LOADER FORMAT OBJECT 


USED TO EXAMINE AND MODIFY 


ERRORMSGS.SYS 


INSTALLS SDOSBOOT.MIK INTO BOOT.SYS, 
SDOS.MIK PLUS I/O PACKAGE INTO i 
SDOS.SYS 

TO BE ADDED TO ANY USER-WRITTEN - 


ASSEMBLY CODE REQUIRING SYSCALLS 
. FOR USE WITH I/O. PACKAGE GENERATION ; 
= 1/0 PACKAGE SOURCE 


SDOS OBJECT 


SOURCE FOR BOOTSTRAP PROGRAM 


MIKBUG OBJECT FOR BOOTSTRAP PROGRAM 
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ERRORMSGBUILD.DO DO FILE THAT BUILDS ERRORMSGS.SYS 


‘SDOSCMDS.BAS* |^». SDOSCOMMANDS SOURCE: BASIC PART . 
SDOSCMDS.ASM* SDOSCOMMANDS SOURCE: ASSEMBLY PART 


SDOSCMDSGEN.DO* f .DO FILE TO BUILD SDOSCMDS.MIK ` 
REQUIRED PROGRAMS: E 


RUNTIMEPACK.MIK : BASIC COMPILER RUNTIME. PACKAGE 


* Optional SDOS customizing package. 
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SYSTEM OPERATION OVERVIEW 


An SDOS session GE of booting SDOS, running. 
applications . or utilities, and finally, shutting. the system 


down. 


Booting is used to bring a copy of Spos Eon a disk into the 
memory of the POMDB eí where it stays for the duration of the. 
session. ) 


Once SDOS is in memory, it loads the DEFAULTPROGRAM and runs 
it as an application program (SDOS does not run programs with 
any special privileges or any. special modes of operation). 
On a development system, the DEFAULTPROGRAM contains an 


operator command interpreter, which allows the operator to 


perform various utility operations.and cause the execution of 


.an application program or development tool (such as.a 


compiler). On turnkey systems, DEFAULTPROGRAM contains an 
application program (perhaps.a menu-driven sub-application 
Selector). The DEFAULTPROGRAM may cause another application. 
or utility program to be loaded and executed (perhaps by 
operator command). When an application/utility program is 
done, it does an (ERROR) EXIT to SDOS, which re-loads the 
DEFAULTPROGRAM and so starts the cycle again. 


Conversations between a program and the ‘operator are _ (by 
convention) done via I/O channel number zero (which is” 
normally OPEN to the CONSOLE: device; SDOS opens channel. zeto 
to the CONSOLE: whenever it finds.a read/write request to 
channel zero with channel zero closed). EXIT closes all I/O 
channels except zero. This allows whatever file has been 
opened for operator input to be passed from one program Co 
another, and is the basis for DO files. 


Errors which occur during execution of an application program - 
are reported to that program via an error code. The program 
may process and recover from the error itself, or it may pass 
the error code back to SDOS for display (via an ERROREXIT). 
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BOOTING SDOS 


"Booting" refers to the process of starting: computer 
operations under an operating system. For application. : 
“systems, this process is usually done once a day. For |. 
development systems, booting may be more frequent. fs 


To get SDOS started, the operator needs to perform. the SÉ 
following steps: l ; 


1.) Ensure that power is on to the computer system and the 
operator's console. Some systems have other peripheral 
devices. that. need to be ‘powered up in orase for SDOS to boot 
< properly. > l l ; | : 


2.) Insert a disk into the disk drive which will be used. as 
-the system boot device. Note: This disk must have valid . 
CBOOT.SYS, SDOS.SYS, DIRECTORY.SYS, and DEFAULTPROGRAM files 
on it, or the boot process will not succeed! Disks with the 
needed files are generated properly = the DO Er 
 SDOSSYSGEN.DO. 


3.) Push the RESET switch on the computer. ALWAYS push RESET. 
before booting; this puts the computer in a known safe state. 
"Depending on your SY EM configuration, one of three things 
can happen: . : ; I 


A) If your system has IDB in ROM, the message 


IDB VX.Y 


will appear. The operator must type Ee the 


boot Geen 


B) If your system has. no "moñitor" program of its own, 


the boot ROM in the computer will take over 


automatically and read in SDOS from your disk. 


6) Some systems have their own monitor program. The 


boot procedure for these systems is monitor dependent, 


but usually consists of some form of computer memory 
¡address entry followed by a "GO" command of some kind. 
See, the. manufacturer's Kee rz e E 


“Some systems, with more than one “kina of disk drive (i. e., a 
.mixture of floppy and hard disks) may ask the. operator which. 


ae drive to boot from. Again, See the manufacturer' s 


documentation. 
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4). At this point, the boot process should have taken over 
automatically. There will be a short burst of activity on 
the chosen (system) disk drive, and then the ae hale banner 
message will appear: ` 


-SDOS, Version 1.0 Copyright (C) 1978 Software Dynamics 


This message signifies that SDOS has managed to successfully 
as itself into Memar yi and has started operations. 


Immediately, thereafter, a message of the form: 
 .mm/dd/yy contentos. 


will appear. This is ARE date that the averen disk was f 
yo eee! the text is the disk identification that was given 
to. SDOSDISKINIT when the. disk was initialized. 2 


If this message tontàins the word "MASTER" anywhere, you 
Should not use the disk for normal operations; only for 
initializing another disk and/or: recovering from disasters. 
It is better to preserve a MASTER disk (obtained from the 
vendor) in a safe place, and use a backup copy in case ` 
something goes wrong. Backup disks can be made with the 
SDOSDISKBACKUP program. p: 


Finally, a "." prompt should appear (if DEFAULTPROGRAM' : 
contains SDOSCOMMANDS). The dot is printed out by the 
operator interface program, SDOSCOMMANDS. Immediately _ 
following the dot, SDOS will prompt the operator for the time 
Of day (see TIME command under SDOSCOMMANDS). Entering the 
time and date completes the boot process, and normal use of 
SDOS may now start. 


In a turnkey system, the prompt displayed is application 


^» program. dependent. 


.Several things can go awry during the booting process. In 
‘Step 3, no reaction at all might occur in response to RESET. 
This means your computer is probably sick, not powered up, 
ete. During the automatic part of the boot (step 4), dead 
„silence may ensue. There are several possible ` causes: the 
-désired disk drive is not powered up, not ready, or does ‘not 
“have the disk seated in it properly; or you may have told the 
ES «computer to boot from the wrong drive (operator errors). 


A (software) damaged or improperly generated system disk, or 
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. use of a disk that only contains, data files as a system disk, 
- Will also cause dead silence, as the required programs to l 
complete the booting process are not present, and the 
computer cannot do anything without those: programs. If this 
appears to be the case, try booting a backup of the. MASTER. 
If the backup of the MASTER will not boot either, then you 
probably have a problem in your CPU, its memory, or the disk 
drive. If the MASTER backup boots, then the original disk 
you tried to boot from is ProbabLY software damaged, etc. 


. The SDOSDISKVALIDATE program may be able to repair a software 
. disk. 


If you “get the SDOS henner but no disk identisicacloñ. your 
System has a serious problem, because the same routine that 


read in SDOS was able to do so only by first ae the disk 


sector containing HE disk identification. 


If the banner and disk identification appear, but no "." or 
prompt appears, DEFAULTPROGRAM on this EE is probably 
damaged. 


Error 1045 (disk read), error 1047 (disk seek) appearing 
during the boot process means your disk is probably worn or 
software SE 


Error 1008 means DEFAULTPROGRAM cannot be found on Che: disk. 


If you have any. of these problems, it is a joon idea to push 
RESET quickly after the problem is discovered to minimize any 
further software damage caused by the malfunction. 


Any other error messages that occur indicate a software 
malfunction and should be reported as a possible bug. 
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USING THE KEYBOARD ON THE OPERATOR'S CONSOLE 


This section describes the various keystrokes that have 
special meaning to SDOS. The actual interpretation of the 
various codes is determined completely by the CONSOLE: driver 
in the I/O package; some systems may id somewhat as a 
result. 


Input line editing: 


Virtually ali. ‘commands and data entered via. the keyboard into . 
.SDOS or a program operating under SDOS are done in "line 
mode",. This allows the operator to type the complete 
command/datum, to correct the input as required, and review 
the input data for correctness before the entire input line 
is handed over to SDOS or the program running. The operator: 


"indicates his satisfaction with the entered data: by- 


depressing the carriage-return key on the keyboard. Prior to. 
doing this, he may correct the entered line using control 
characters described below. Once the RETURN key is pressed, 
there is no way to prevent the entered line from being fed to 
SDOS or the program. Once input is requested, no action is 
taken by the program until «CR» is depressed. 


Control characters used to edit input lines: 


^H BACKSPACE; DELETES PREVIOUSLY TYPED CHARACTER 
AND ERASES IT FROM SCREEN - 

e SR TABS THE INPUT, PASSED TO PROGRAM AS A TAB 
CHARACTER | a T E 

“M CARRIAGE RETURN, CAUSES INPUT LINE TO BE 

: PASSED TO PROGRAM 
^R RETYPES THE PART OF THE LINE ENTERED SO FAR 
^X . CANCELS LINE ENTERED SO. FAR; TYPIST MUST 


. ENTER COMPLETE NEW LINE 
` RUBOUT DELETES PREVIOUSLY TYPED CHARACTER; ECHOS THE 
CHARACTER .DELETED 
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Special control characters: 


Special control characters are used to interact with SDOS or 
the BASIC Run-time Package to perform various functions. 
None of these special characters are passed to a program 
“requesting input. 


^A 


Toggles "fold" mode. In fold mode, Low saco letter 

keys are translated automatically to uppercase. When 
not in fold mode, lowercase letter keys are passed to 
programs as lowercase. 


Used to set breakpoints on me numbers in BASIC 


` programs. 


owe will cause any program to be killed if it. is not 
KILLPROOF. Logging is terminated and any DO. file is 
aborted. Two “C's must be typed in succession (to ``“ 
prevent the operator from accidentally killing a 
program). The type-ahead buffer is cleared; “P and 
^S modes are exited. A Single “C will be echoed, but 
will have no effect if any other key is struck before 


a second ^C. This allows the operator to determine 


if SDOS has not died completely by typing “C<LF>; the 

^C will be echoed; and the <LF> will prevent the next 
^C from killing the program running. No ^C echo is a 

good sign that SDOS has died. d. 


Causes system debugger to get control as though a 
non-maskable interrupt had occurred. If the 
currently running application is KILLPROOF, ^D is 
ignored. Some systems do not have this feature 
implemented; in these systems, ^D is simply another 
character. ME P 


Used to go from a breakpoint in a BASIC program. 
Also exits “y mode. 


Toggle page mode display. If the page mode toggle is 
on, SDOS will print the next 24 (a screenful of) i 
output lines on the screen, beep, and then stop 
output. The user may then type “Q to see the 24 | 
lines following, or “P to leave page mode (which will 
cause SDOS to print without pausing for operator 
intervention). . The application program is frozen 
until ^P or “Q is typed. Page mode is normally used 
when listing a large file on the CONSOLE: device, and 
the operator wishes to inspect the listing closely. 
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If a terminal does not sn for an abnormally long 
period of time, it may be that page mode is enabled, . 
and.24.lines have been displayed, or simply that no 
output is being generated. 


Q Continue output (see UP ER, 


: CS. Stop output now. Used by operator to E Stop 


the computer, from printing more text on the CONSOLE: 
device. The operator must type “Q to allow output to 


- continue. 
^r | Trace line numbers of a BASIC program. 
SR Single step lines of a BASIC program. 
“Z hs Causes an end-of-file condition to occur on the 


CONSOLE: device if typed in response to an ASCII read ` 
request. l 


<ESC> Signifies operator would like to interact with 
program. This allows the operator to. signal a busy 
or compute-bound program an attention request without 
killing the program. The program can sense an- 
operator attention request, and process it at its 
leisure. There is no guarantee that a particular 
program pays any attention to an operator attention 
request. The type-ahead buffer is cleared when <ESC> 
is pressed. 


| Type-ahead 


All keys: (except the special control characters) SEU. by 
the operator when the currently running program is not 
waiting for input are not echoed, but are saved in a 
"type- -ahead" buffer. ‘They are processed and displayed when 
input is required, as: though the operator had typed them then 
and not earlier. This allows the operator to get ahead of - 
the program's input 7 if he knows what data will be 


needed next. 


i 
| 
H 
| 
| 


"` Some programs operate in "binary" input mode. In this mode, 
all keystrokes including the special control characters aré^ > 


given-to the program as is. No input editing is possible 
without the program’ s aid, so editing is thus 
program-dependent. | The majority of programs operate in line. 
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input mode as described above. (not in binary iode) unless 
. Otherwise stated, all programs Ke in ine input mode. 
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DEVICE and DISK FILE NAMES 


Stored data is given a name (by the user) so that he may 
later retrieve that data. This name is known as a "file" 


“name. Data may also by read or written to a peripheral 


device; to indicate which device, a "device name" is used. A 
single device (such as a disk) may be able to store many 
files; in this case, the device name and the file name must 
be given together to select the proper file. The combination 
of device name and file name is also called a "filename". 


A device name is composed of any sequence of alphanumeric 


“characters followed by a colon; the first character must be 


alphabetic. Lower case alphabetic characters are treated as 
being equivalent.to their upper case version. The device 
name is generally a mnemonic related to the actual English 
-name of the device, with an optional trailing digit if more 

^ than one of that kind of device may be connected to à system. 
Disk device names are short because they tend to be typed. 
frequently. A misspelled device name will be promptly caught 
by SDOS. 


Typical device names are: 


CONSOLE: . The user's console. Available in all 


SDOS systems. 
D@:, Dl: Disk ð, 1, 2 ... One name for each 
f disk unit. 
DISK: Name of default disk (see DEFAULTDISK 
l command of the command. ARETE EEE) 
LPT: Line Printer... ; 


CLOCK: The time and date device. 
Disk file names have the following form: 


filename 
or 
` filename (integer) 


The filename must be from one to sixteen characters, from the 
Set Š, ., A-Z, 0-9, or a-z (lowercase is automatically 
treated as uppercase). The first character of the filename 
must be $ or A-Z (not a digit or "."!). The optional . 
"integer" in parentheses is used at file creation time to 

. allocate enough disk space to contain the number. of data 
bytes specified by "integer". Names longer than 16 
characters (excluding the parenthesized file size) are not 
legal and will be rejected. 
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Seiad EXTENSIONS 


An "extension" is an agreed- upon suffix to a file name that ` 
gives some useful information about the contents of that. 
file. | SDOS disk filename extensions consist of a period 

. followed by one or more letters. A particular extension 
indicates a particular file type. An example might be 
ABC.TXT; "ABC" is the name by which the user would like to 
refer to the file; .TXT tells him that the file contains raw 
text (as opposed to, say, a computer program or list of prime 
numbers). Since an extension is merely part of the filename, 
and files can be named (or renamed) arbitrarily, these . 
“extensions are merely conventions. Their ütility is directly 
proportional to the amount of PESE invested by the user in 
Sticking to the conventions. 


The: following” extensions are defined: and used by standard SD 
producteur 


. DO For command ("DO") files 
.MIK For files containing MIKBUG obiect 
7 records ` 
.BAS ` | For files containing the Source of 
; BASIC programs. : 
. DOC . For files containing- text. to be fed 
> . to a document formatting program 
ASM For files containing assembly source 
PME code o 

¿TXT For files containing raw. text 
. DAT For files containing data other than 
; I text a 
~LPT. ` For files containing listings 

f meant for a printer (i.e., an LPT:) 
TK For files containing SDOS system data 


no extension For executable programs, i.e., 
for. SDOS load record binaries. 


Typical disk file names: 


-MYFILE 

PAYROLL. BAS 

MONTHREPORT. LPT 
.-. D3:ABC 

DIS: EDIT 


o c 
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THE COMMAND INTERPRETER 


The command interpreter (SDOSCOMMANDS) is a utility program 
which provides many simple but frequently used file 
manipulation commands. It also allows the operator to cause 
the execution of any program, to perform canned. sequences of 
operator commands, and to perform some miscellaneous utility 
operations. The command interpreter also provides a simple, 
relatively consistent format for passing parane eaS a as 
file names) to user programs. . 
On SDOS development systems, a copy of the command ze 
interpreter is usually stored in the DEFAULTPROGRAM file, so 
that whenever an application program finishes execution, Che 
command interpreter is loaded and begins execution. Turn-key 


. systems built around SDOS usually have a particular 
“application program stored in DEFAULTPROGRAM with some method 
` to allow the operator to execute SDOSCOMMANDS (which contains. 


the command interpreter). 


The command interpreter BED a "." to indicate it is ready 
to execute another command. The examples show this dot, but 
it is not typed. in by the operator: The command format 

expected is: : 


<command> <parameters> 
Or 
<command> 


where the parameters are separated from the command by one or 


more blanks. Some commands require no parameters; in this 


case, information in the parameter field is ignored. Other 


commands will select a default set of parameters if an empty 


parameter field is given. 


Input [to the command EC is done in line mode. The 
operator must push the «CR» key to cause the command 
interpreter to act. All editing keystrokes are valid. The 


command interpreter treats all type-in as though it were done 


in upper case; the examples are shown in upper case. 
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Commands handled by the command interpreter are: 


FILES ` List the names of files on a disk 
LIST List the contents of a particular 
f file f 
COPY Copy the contents of a file from one 
| place to another 
RENAME Change the name of a file 
DELETE Make a file disappear 
DISMOUNT Causes SDOS to "let go" of a disk 
DEFAULTDISK ` Directs SDOS's attention to a 
particular disk f 
TIME Set/display time and date ` 
FREE Display amount of available space 
: on a disk. 
. VERSION Displays. version. number of command 
interpreter ` 
HELP Converts an error number: toa 
i ‘corresponding text message 
DEBUG Load a test program and dive 
control to debugger 
LOG Makes copy of console session 
f and places in a file 
CLOSELOG ` Stops copying console session 
DO Execute a canned sequence of 
commands 
- LABEL Target point of GOTO or -IFERROR: 
GOTO Skips over canned commands. 
` IFERROR Conditionally skips over canned 


commands 
Comment line 


If a command is not. recognized, it is assumed to be the name 
of a program (file) to be executed. Most of the complex I 
utility programs (such as SDOSDISKINIT and SDOSDISKVALIDATE), 
along with user programs, are invoked in this fashion . 
allowing invocation of "commands" external to SDOSCOMMANDS 
and commands internal to SDOSCOMMANDS in the same fashion. 


Parameters given to commands not recognized by SDOSCOMMANDS 


are passed to the program specified as the first line of 
console input (i.e., the first READA (or INPUT) of a program 
will read the part of the input line not occupied by the .- 
command name). 
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FILES 


The FILES command is used. to detérnine what disk files. reside 


on a disk. It will also display a subset of the files Mose 


names match a pattern given by the operator. 
The FILES command has the syntax: 


FILES 
Or 
FILES «device? 
or 
; FILES «device» ¿ello EE 


` «device» is intended. to be the name of a disk drive (such as 


D@:, D1:, etc.). If <device> is not. given, DISK: (the 
default disk; See E command) is assumed. ; 


The <filename pattern». is sea to e which filenames on 
the specified disk are to be displayed. The «filename | 
pattern> consists of..any valid filename, with portions 
replaced by an "*", The "*" is known as a "wildcard", and is 
used to signify any sequence of zero or more file name 
characters.  Filenames will not be displayed by the FILES 
command unless they match the pattern given. A match occurs 
when a filename under consideration has all of the (legal) 
Characters given by the pattern, in the order specified by 
the pattern. Wildcards are used to match the rest of the 
filename. -Wildcards may occur at the beginning, end, or 
middle of a pattern; multiple wildcards are allowed. Doubled 
wildcards (**) are treated as single wildcards. Thus, A* 


. natches ABC, APE.BAS; B*.ASM matches BOUND.ASM and B.ASM; 
*EN* matches any filename that contains the letters E and N 


adjacent; *E*N* matches any filename that contains an E 
followed eventually by an N. If no «filename pattern»? is 
given, all filenames of files on the Selected drive are 
displayed (i.e., * is used as the «filename pattern»). 


The FILES command displays the identification of the disk 
Specified, one line per filename, and the percentage of the 
disk space occupied by the files EE 


Each filename displayed: is displayed with data concerning the . 


physical | disk space occupied (LCNs), the virtual disk space 


occupied | (BYTES), file protection codes, and the date: of 


` creation of the file. ` 


. LCNs give the space allocated to a file in terms of clusters. 
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BYTES describes the highest number.data byte written to the 
file. Note that LCNs is not necessarily a direct function of 
Bytes due. to the possibility. of a file being sparse (see SDOS 
DISK FILE STRUCTURE and also, ERRORMSGS.SYS in example: 
below). i E : SÉ 


The protection Ee are listed as D for a delete protected 
file; W for write protected, and blank for no protection. 


Sample directory listing: 


«FILES Dl:*S* Sé 
Files on... FRED'S GAMES DISK 


Filename + LCNs Bytes Prot Date  . 
SDOS.SYS 28 23851 D 08/03/78 

` BASIC . E TOTUM ic 11147 D 28/03/78. . 

¡STARWARS 7 . 5283 | 09/12/78 
GALAXIES ^ quA 611 : 29/27/78 
STARTREK 5 3554 10/02/78 
STRATEGY 6 4949 - 10/22/78 
ERRORMSGS.SYS 10 199655 11/07/78 


Total of 70 clusters in 7 files for 22. 7% of disk capacity 


Hitting ESCape during a FILES listing will abort the command. 
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LIST 


LIST is weed to quickly scan the contents of a file 
. containing text, or to copy a text file ES some printing. 
j device to obtain a hard copy. 


The LIST command has the format: . 


LIST <filename> 


or 
LIST <filenamel> TO <filename2> 


; The word "TO" must be separated from the <filename>s by at- 
" least one blank on each side. . 


The first form is treated as though LIST <filename> TO 
CONSOLE: had been typed insteád; this prints a copy of the 
file on the operator ' s CONSOLE: . The file may be inspected 
at whatever rate is appropriate for ene operator by judicious 
use of the “P, “S, and “Q keys. 


The second Ge causes the command interpreter to CREATE the 
file specified by <filename>, and copy <filenamel>'s contents 
to. <filename2> using ASCII Times mode reads and writes. This 
is particularity. convenient when used as. follows: 


LIST <filenamel> TO LPT: 


which causes the selected file to be printed on the line 
printer. 


When bolta ing a small DO files 
LIST CONSOLE: TO WHATEVER.DO 


is a convenient way for the operator to key in the text for 
the DO file directly without use of the EDITor. Exit from. 
this mode of data entry is accomplished by typing ^Z, which 
signifies end of file for the CONSOLE: device. : 

| 
‘To copy a text file from a paper tape reader to a disk file, 


LIST READER: TO targetfile 
` would suffice. 


LIST can be used to copy a text disk file to another disk 
file; but it cannot be used to copy a non- text, file. Since: 
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the COPY command will copy either text or non-text disk 
, files, moving copies from one disk file to another is. l 
"generally done only with the COPY command. The LIST command 


almost invariably is useful only when an 1/O device other 
than a disk is involved as à source or a target. 


Hitting ESCape will abort the LIST command. 


Because LIST is implemented as a BASIC program, very long 
lines may be truncated when LISTing a file. 


Copyright (C) 1978 Software Dynamics 
-29- 


SDOS USER'S MANUAL 


COPY 


.The COPY command is used to make exact copies of disk files 
or the. data received from an I/O device. It. can also be used 
to perform a simple disk BACKUP or to append several files 
together. 


The form of the COPY command is: 


— COPY <sourcefile> TO <destfile> 
- Or 
COPY <sourcel>, <source2>,.., TO <dest file> 


A new copy of <destfile> is CREATEd (so an old file by that 
name will be lost; no warning is given), and the. source files 
are copied in the order specified into the newly created 
file. The first source file is opened. before the destination 
file is created. The copy is performed using binary reads 
and writes, so that the file contents are copied iY: 
byte for byte. 


The COPY command uses all available memory as a large. buffer 
to optimize the COPY; this makes COPY move data considerably 
faster than a very simple, one-byte-at-a-time copy program. 


COPY will copy sparse files to another disk file, preserving 
the sparseness property, but it will not preserve the ^ 
sparsity if the target file is not a disk file. IL will not 
necessarily preserve the exact structure of the sparseness, 
so the number of LCNs in the copied file may not match the- 
number in the source exactly. COPY preserves the sparsity. by 
simply positioning past large blocks of zero data bytes in 
the source file. 


If the destination is.a disk device (i.e., Dl:, not a disk 
file), then COPY will ask for a verification before it- 
proceeds; this prevents accidental copying onto a 
file-structured disk with the consequent disasterous results 
of destroy ng the file structure on the target disk. 


- ¿COPY PRIME.BAS TO D1:PRIME.BAS 


moves the file PRIME.BAS from the default disk to Dl: 
(copying multiple files from one disk to another is more 
easily accomplished via the SDOSDISKBACKUP program). 


.COPY FIRSTPART.ASM,SECONDPART.ASM TO WHOLETHING.ASM 
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appends FIRSTPART and: SECONDPART together. No data bytes are . 


inserted between the two parts. 


. COPY ERRORMSGS . SYS TO Dl: ERRORMSGS.SYS. 


copies the sparse file ERRORMSGS. SYS. Note that EE 


no operator action is required to preserve the sparseness. 


If an * is used as the filename part of <destfile>, then the 


‘filename part of <sourcefile> is used as the destination 


filename. If <sourcefile> is a list of files, or ‘simply a 
device name, using * in <destfile> is not legal. 


.COPY PRIME.BAS TO Dl:* 


copies PRIME.BAS from the default disk to Dl:. | 


To place a file on a disk without any file structure Se 


‘though the disk were a paper tape, with LSN Ø being. the first. 


block, LSN 1 being the second, etc. ) the iyi needs to 
be done: 


.DISMOUNT Dn: 
.CoPY file TO Dn: . l 
Are you: sure you want to write on the disk DEVICE? YES 


The DISMOUNT ¿command forces the map algorithm on Dn: to 
become "1" (a convenience when later trying to read the 
disk). Note the verification required before COPY will 


‘begins... 


Recovery of a file written onto a disk as above is effected 
as follows: 


, DISMOUNT Dn: 
.COPY.Dn: TO AFILE 


This will recover the file; unfortunately, it will also slurp 
the unused part of Dn: into AFILE so that special editing of 
AFILE is needed to complete the process. Text files written 


‘onto a disk device are usually recovered by using the EDITor 


to "edit". the. text. from the disk device. 


A simple disk backup scheme is effected as follows: 
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.DISMOUNT- Dn: 

.DISMOUNT Dm: 

.COPY Dn: TO Dm: 

Are you sure you vant. to write on the. disk DEVICE? YES 
.DISMOUNT Dm: I ! 


This copies Dn: to Dm:. Neither Dn: nor Dm: need to have a 
valid SDOS file structure; any disk compatible with the drive 
can be copied in this fashion. If the source disk contained 
a valid SDOS file structure, SDOSDISKVALIDATE can be used on 
Dm: after the copy is es to change the disk 
identification. ; 
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RENAME 


The RENAME command is used to change. the name of. a disk file. RUM 
^. The file is not moved or. modified in any way. E 


The RENAME ` command has’ the following form: 
RENAME <oláfile> TO <newfile> 


only disk file names are allowed. Renaming a file to a 


device name is illegal, as is renaming. a file on one disk to ` 
. a filename with. a different disk specification. If Dn: is ^ - 
owe specified with solarier, it should also be Specified with 


<newfile>. 


-RENAME ABC. TXT. TO PRIMES. BAS Gë EE 


EE the name of the file ABC. TXT on the default disk. to Sa 


PRIMES.BAS (on the default disk). 


RENAME D2:TESTDATA TO D2: LIVEDATA 


renames TESTDATA, a file that is on D2: instead of on the ` 
default disk. JE ` P 
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DELETE 


The DELETE command is used to erase the names and contents of 


a specified set of disk files. The space used. by those files . 


is returned to available space on the disk that contained the 
file, for re-use later when more. files are created or. 
extended. l i : 


The form of the DELETE command is: 


DELETE «filel»,«file2»,... 


The specified list of filenames is examined and each is | 
` deleted in turn. A device specification will ensure that the. 
file to be deleted was really on the specified disk. If a 
Specified file cannot be found, or an.error occurs, the > 


DELETE command complains and ignores the remainder of the 
list. f = l i pog Ee c UE l 


A filename may contain wildcards (see FILES command). The 
DELETE command will delete all files whose names match the 
pattern given. The deletion process can either be automatic 
or verified in each individual case; the latter allows 
selective deletion. When the DELETE command discovers a 
wildcard for the first time, it displays: 


Ask before doing the delete? 


A response of NO will cause DELETE to find all filenames that: 
match the pattern, delete the corresponding files, and list 
the names of the deleted files on the log device (normally 
CONSOLE:). Any other response is a0 Peete’ as YES; this. 
causes the DELETE command to ask I 


Delete <filename>? 


for each filename found that matches. A response beginning 


with Y to this question will cause <filename> to be deleted; 


any other response will cause <filename> to “bo. left: intact 
(i.e., not deleted). 


If another filename is encountered contatning a wildcard, the 
DELETE command deletes matching files in the verification 
mode Supplied the first time it asked 

"Ask before doing the delete?" is 


The wildcard delete can be an.enormous timesaver if used 
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oh It can be a disaster if used carelessly! Beware. 


"DELETE D2:ABC 


does what it Says; ABC is deleted on device D2:. 


. «DELETE Dl:*.BAS,D2:Q.TMP 
Ask before doing the delete? Y 
Delete JUNK.BAS? Y ! 
Delete USEFUL.BAS? <CR> 
Delete OTHER. BAS? YES 


This sequence deleted D1:JUNK. BAS, D1: OTHER. BAS, ana: 
D2: Q. TMP; USEFUL. BAS was. retained. ! 


© .DELETE *ar 

- Ask before doing: ine delete? NO 
JAM.TXT 
INVENTORYDATA 
TRASH.JNK 


Note that. the file INVENTORYDATA was deleted; if this is what 
the operator intended, fine; if not, he should have been more 
careful and bs the verify option. 
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" DISMOUNT 


The DISMOUNT ' command: is used by the operator to notify SDOS 


that he is about to remove a disk from a disk drive. 


IMPORTANT: FAILURE TO USE THE DISMOUNT COMMAND BEFORE ` 


REMOVING A DISK FROM A DRIVE MAY RESULT IN 
LOST DATA SR A DAMAGED ELLE SYSTEM ON THAT 
; DISK! 


Replacement of one: disk by another without notifying SDOS may 


damage data on POIN disks! : 


The form of the DISMOUNT command is: 


DISMOUNT. <diskdevicename> | 


This Sd. causes SDOS to write all modified disk sectors 


(for the specified disk) that remain in the computer's memory 
back to the specified disk, thus ensuring its integrity. 
(This command also causes SDOS to "let go" of the system 
files DIRECTORY.SYS, DISKMAP.SYS, and ERRORMSGS.SYS on the 
specified disk, and forget about any unmodified disk sectors 
it may have in memory). 


In an effort to prevent system crashes or the operator from 
accidentally damaging his disks, SDOS does write all data 
that belongs to a disk back to that disk when an application | 


program stops (EXITs). This means that when the "." is first : 


printed by the command interpreter after execution of any 
program, the data and file structure of all disks is safe and 
completely up to date. 


There is no corresponding "MOUNT" command; SDOS does an 
implied MOUNT when its attention is directed to a disk drive 


it thought was dismounted. 


.DISMOUNT DB: 


releases D0:; the operator may remove the disk in D@:. when 
the "." prompt is printed after completion of the command 


(NOT BEFORE!). If a "Write Protect" error occurs during a 
dismount, the operator should repeat the dismount until the 
error no longer occurs and then run SE on the 


‘disk. 


Note: Before shutting the system down (at the end of the day 
or before powering the computer off), all drives containing 
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disks MUST be dismounted, one at a time. 


Copyright (C) 1978 Software Dynamics 
-37- l 


SDOS USER!S MANUAL 


I e 


The DEPAULTDISK command is used to tell SDOS which disk ‘drive: 
is to be used when a filename without a EE device 
prefix is given. The form is: + 


` DEFAULTDISK <diskdevicename> 


When SDOS is booted, it selects a DEFAULTDISK. which. 
corresponds to the device from which it was booted (this is 
usually named D0:). This allows un-prefixed file names to AM. 
automatically refer to files on the. boot device; that is, ABC 
would really be interpreted as D@:ABC (D3:DEF is. interpreted 
as file DEF on D3: because of the explicitly given device. 
prefix). The device name DISK: is.a dummy name for the 
currently chosen DEFAULTDISK (i.e., ABC is. the. Same as D0:ABC.. 
is the. same as DISK: ABC in this case). f 


When the pitos Dee he is WEE references to 
files on a disk drive other than the boot device, he can 
minimize his typing (of devicenames) by changing the 
DEFAULTDISK to,the drive he is using PRENET Gat This is 
done by typing ` f ` 


.DEFAULTDISK D2: 


where D2: is the disk drive which contains the files he is 
. referencing frequently. All further references to ABC will 
. then mean D2:ABC instead of DÜ:ABC as it was previously. 


The newly chosen default disk must have all the desired 
programs on it, or the operator will have to prefix the. 
program name with the appropriate device. For instance, if a 
PAYROLL program is stored on D@:, and the default disk is 
currently D2:, to run the PAYROLL program, the operator must 
type 
. DO: PAYROLL 
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` TIME 


The TIME command. is used to either display the current time 
of day and date, or to set the time of SE and nake: The 
form is: i n 7 


` TIME SC T 
or l 
TIME 


The first form allows the operator to set the SDOS Glock. HH ` 
.is two digits which stand for hours based on a 24 hour. clock 


. (88. is midnight, 06 is 6 AM, .12 is. midday, . 18.is.6. PM, and.. SE 


is 1l PM). MI is two digits standing for minutes of the 
hour, ranging from Ü to 59. MO is two digits for the current 
month, with January = Øl, February = @2,... December = 12. 
DD is the day number within the month, 1 to 31. (you Gan tell. 
“SDOS that today is February 31, and it won't complain).  YY - 
is the last two digits of the year. amber for 1979, it is 
79, SE 


. There must be only a single space EUM and the hours, 
and a single space between minutes and the month number. 


When SDOS is first booted, it knows its clock has not been 
set. The command interpreter will print out the word TIME 


followed by a space, and expects the operator to complete it. ` 


If the operator does not complete it, SDOS will periodically 
pester the operator in the same fashion (this helps ensure 
that files get marked with their correct creation date, ‘that 
reports printed are dated properly, etc.). 


The time may be changed at will.  SDOS will then s> 
update the current time as time passes, adjusting the date ` 
and year ee if necessary. 


Example: 


To set the time. to 3: 14 PM, peat 3, 1979, the operator 
types: : i 


TIME 15:14 4/3/79. 


Note that leading Ø digits need not be typed. 


The second form of the TIME command displays the current time... 


in the form HH:MI:SS MO/DD/YY, where SS is the current time 
in seconds. ` 
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.TIME 
15:14:08 04/03/79 
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FREE. 


The FREE command is used to determine how much disk space is 
available (unused) on a disk. The form is: 


FREE 
or 
Pree <diskdevicename> 


The first form tells the Seege the amount of free space on 


3 the default disk, and is identical to FREE DISK:. The second - 
e ÑO rm allows the-operator to EE aa s cu s M. eset 


examined for free space. ` 


de The data displayed indicates the number of available clusters 
um and the percentage. of the disk capacity. available... onus. 


FREE D2: | | 
A total of 25 free clusters for 12.5% of disk capacity 


Small disks with less than 5% free disk space probably do not 
de have enough available space for another file. | 
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VERSION 


The VERSION ‚command is used to determine which version of the. 
command interpreter is actually being used, and is needed 
usually only if a bug is discovered. SD programs all display. 
a banner identifying themselves when loaded; the command n 
interpreter is the only exception. This command prints the 
banner for the command interpreter. E" PEE l 


. VERSION 
Version 1. 1 1/30/79 


> This documentation. matches PN interpreters whose version 


number matches that given in the example above. - The MO/DD/YY 
is for internal use at SD. : 
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HELP 


ú The HELP command is used to convert an error number into a 
text string that people understand. “Normally, this 


conversion is done automatically by SDOS;. however, there are 


“times when some transient hardware. or Software failure will 


prevent SDOS from printing the proper. message, and it (or 


Some program) will be forced to print a number instead. The 


HELP command can be used by the operator to force SDOS to 


veut 


again try:to convert the number to its corresponding nessadgs 


The form is: 


HELP" 
0r 
HELP «number» 


- HELPO-by-ltself woods "print the message for the last error 


number that was printed out". HELP with an explicit number, 


"means "print the error message corresponding to this number". 


.HELP 1008 
No DEFAULTPROGRAM on default disk 


If SDOS cannot convert the number to the eer 
string, it will simply print out 


ERROR «number? 


as its response. This can happen if there is no. 
ERRORMSGS.SYS file on the boot disk or if the ERRORMSGS. SYS. 
file is damaged. ` 


.HELP 1845 
Disk Read Error 


The operator cannot be sure that a disk read error: really did 
not occur while processing the HELP command. 


Copyright (C) 1978 Software iE 
-43- 


Responses to certain error numbers can be somewhat ambiguous:. 


| SDOS USER'S MANUAL 


DEBUG .- 


The DEBUG command is used by an E language programmer 


to load a program to be tested, and pass control to the local. 


debugger program before the Program under test is executed. 


- The form is: 


i Fo 


‘The program specified by filenames is loaded into 'the user's 
memory space, and control is passed to. the local debugger. 


A small program placed in Che üpper part of page zero is used 
to perform this process, so none of the load records may: 
Select page zero or the system may crash. .The small program. 
uses the LOAD syscall to load the program. ` It uses a DEBUG S 
syscall to start the debugger,- after setting the return- 


address for the Gd age e the ee address of ake N. 


loaded program. 


For systems using IDB (the SD debugger) , ` the folicwing.. 
SEET is relevant: 


.DEBUG TEST.MIK 
P-2800 A=5E B=57 C=C4 X-575E S=821A */ BDU100 8887/ 00. 
IDB V1.1 


The Program Counter is set to the Start address specified by 
the load records. e propina or real- ~time execution may 
Be done immediately. 
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LOG 


The LOG command is used to create- a copy of a. terminal t. 
session, in a file or on a printing device. -This is à handy 


| way to get a hard copy of the list of files on a disk, to. 


generate printed examples of how to use a EE for 


"O O bugs in a programe The form is: 


LOG <£ilename> 


eps first checks to see d£ LOGging : is- already active; if fno 


it complains. If not, «filename» is CREATEd, and all further 


= input and output to: thee “operator's: CONSOLE: (channel 0) is ` 


also listed to the Specified file. 


.LOG LPT: 
«FILES D2: 


. CLOSELOG 


is a convenient way. of obtaining a hard copy version of "hé 


list of files on D2: (the EPOSELOG causes the s of the 
console display to cease). 


If a "bug" occurs, the operator should turn on logging to a- 
hard copy device, cause the bug to be displayed on his 


Screen, turn off logging, and send the resulting hard copy to 
SD. This allows SD to see precisely the circumstances under 
which the problem occurs and enables us to act more swiftly.’ m. 


.LOG LPT: : 
. TIME <CR> (date it, please!) 
.* BUG: DOESN'T XXXXX (tell SD the problem 


| using comments) 
. <demonstration of bug» l l 

| .CLOSELOG |. ; 
Killing a program e C^C) causes logging to cease, 


For more detail, see SYSCALL: CREATELOG. 
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CLOSELOG 
The CLOSELOG command is used to turn Teague off. To start 
logging again, another DO command needs to be issued. The 
form. is: | 
|CLOSELOG. 
| No parameters are Se 
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DO 


. The DO command allows the Buc SP to Epean that the. 


contents of a file àre to be used instead of keyboard entry. 
This is particularly useful when a sequence of commands is 
EEN frequently. The format is: KS 


| DO <filename> 


The file is OPENed, and lines read from the file are “treated 
just as though the operator typed them on the console 


himself. These lines are used not only for commands to. the o. 
command interpreter, but also as inpüt for other keyboard a 
requests by any programs that are run. Actual keyboard. entry i 


is not used until the contents-of the "DO" file are pES 


|» completely processed. 


If an error of any kind occurs. while T i ommana interpreter 


is executing à DO file or the command interpreter gets 
control because of an error, then it will "abort" the DO file 
and start accepting keyboard input again. The: ESCape key may 
generally be used to cause an "Operator Requested Attention" 
error; if this does not work, ^C^C will always stop the DO 
file. I ae 


The following creates a DO file to execute a PAYROLL program, . 
DELETE ABC.TXT, and finally execute an INVENTORY program. 


.LIST CONSOLE: TO DOALL3.DO 


PAYROLL 
DELETE ABC.TXT 
INVENTORY yi fy 
^2.DO DOALL3. DO l typed by operator 
. PAYROLL printed by computer 
«payroll executes> | 
. DELETE ARC. TXT ! printed by computer 
` INVENTORY i ; printed by computer: 
<inventory executes> 
š f E computer waits for 


Sper as 


If a hard copy of the console session BEEN from use SÉ a 
DO file is desired, then a LOG command preceding the. DO 
should be executed. In this case, all input is read from the 
DO file, and all output goes to the chosen LOG file. No ` 
display will be made on the operator's screen while some part 
of the DO file is left to be executed. i the above DO’ 


o Ẹile:- 
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.LOG LPT: "ur Pat hard copy of session to. 
printer 3e | s 
.DO DOALL3.DO ag 
<payroll executes, ABC. TXT is deleted, INVENTORY’ 
executes; NO CONSOLE: DISPLAY> 2 
zw a DO file is complete 


. DO files can only be nested one level deep, so “invoking* a. 


second DO file from a first causes the command interpreter-to ` a 


completely E Lt was processing the first DO file; 
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LABEL 


The LABEL command is used to mark à target point in a DO file 


- for GOTO and IFERROR commands, and is userul only in a DO 
file. The form is: 


. LABEL <labelname> 


where <labelname> is Ne from the Word LABEL ey a 


- single blank, and consists of any sequence of non-blank 


characters. It is conventional. to use only alphanumeric 


-. characters in the <labelname>.: This command does nothing, 


and is totally ignored if the command interpreter is not 
searching for a LABEL as a result of a GOTO or IFERROR 


command . 


Example: 


LABEL THISISTHEPLACE 
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GOTO 


` The GOTO command is used in DO files to skip over 
sub-sequences of commands and data entry. It is useful only 


` in conjunction with Ene: IFERROR and LABEL commands. The form 
is: : 


GOTO <labelnane> 


where ciubeknaney has the form described in. the LABEL 
| command. 


This command causes “the command interpreter to read and Ze 
ignore AE lines until one is- encountered of the form: 


LABEL <labelname> 


with a <labelname> that “matches ‘that of the GOTO. Once the. 
matching LABEL statement is found, the command interpreter 
goes back into a mode of executing commands. End of file on 
the DO file will force the command interpreter to leave GOTO 
mode and resume normal operation. - 


If the operator ever ends up in the command interpreter. 
(i:8., the "a" prompt), and the command interpreter is 
echoing but ignoring everything he types, the command 
interpreter is probably. doing a GOTO to a <labelname> it did 
not find. Typing ESCape or ^C^C will fix the problem. 


.DELETE ABC.TXT deletes ABC.TXT 
.GOTO SKIPIT ` a 
.DELETE DEF.TXT skipped by GOTO ‘command! 
" ¿LABEL SKIPIT 
^ f . normal processing continues 
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IFERROR 
l The IFERROR command eviews: DO. files to: recover from 
l processing errors of virtually any kind. The form is: 


^ IFERROR <errornumber> <labelname> 


where. <errornumber> is an integer and is. separated From 
 "IFERROR" and the <labelname> by at least one blank. . l 
<labelname>. is the same as described for the LABEL command. 


i df the command interpreter regains control after an operation 


which did not hàve àn error, then the IFERROR statement does ` 
nothing: (is ignored). LE po 


If the command interpreter regains control immediately after 
an error occurs, and it is processing a DO file, then it will 
abort that DO file unless there is an IFERROR command that 
‘contains an <errornumber> equal to that of the actual error. 
The command interpreter determines this by reading commands. 
from the DO file. If the next command. is an IFERROR, the 
actual error number is compared to the error number embedded 
in the IFERROR command. If there is no match, the command 
interpreter reads the next command line from the DO file and 
processes it likewise. If the command is not an IFERROR, the 
DO file is aborted. This means that all the errors for which 
. the DO file must recover must be listed, one per IFERROR 
Statement, at the point in the DO file where the error would 


. be detected. 


-If an IFERROR statement is found ste a matching error 
number, then the command interpreter "forgives" the error, 
and does a GOTO to the specified label. This conditional. 
GOTO allows blocks of commands to be conditionally skipped. 
Coupled with the GOTO command, virtually any error recovery 
may be implemented. 2 


If, while looking for a matching 1PERROR, the command 
interpreter encounters end-of-file on the DO file, the 
command interpreter forgets the error. occurred and. re- enters 
normal command interpretation mode. 


The following DO file will make CURRENTDATA into BACKUPDATA: 


^* GET RID OF OLD. BACKUPDATA oe 
DELETE BACKUPDATA 

IFERROR 1011 WHOCARES 

LABEL WHOCARES. 
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RENAME CURRENTDATA TO. BACKUPDATA 


- The IFERROR statement handles: the "No such file" case by 


doing EE nothing except D UN Edgy the error. 


PH following DO file prints a MONTHLYREPORT on the line ` 
printer if the report has already been manufactured by a 
GENERALLEDGER program. If the report has not been 


- manufactured, then the DO file runs the GENERÁLLEDGER program E 


to obtain it, and then prints it out. 


LIST MONTHLYREPORT TO LPT: 
.IFERROR 1911 MAKEREPORT. 
- GOTO DONE .- ` 
LABEL MAKEREPORT 
. GENERALLEDGER : : 
_ :bIST-MONTHLYREPORT TO LPT: 
Š “LABEL “DONE © i 


Error numbers are listed in the section on errors. 
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* (Comment) 


B The * command simply allows the operator to annotate what he 
. is doing at the command interpreter level. The form is: 


-* «any text ended by «Cm» 


"The command is totally ignored; the command interpreter 
immediately prompts the operator for the next command. 


This command finds uses in three places. First, when 


. logging, an * command can be used to clarify what the 
operator is doing for a later reader of the logged file. 


Second, when used in.a DO.file, the * can act as a Signal to 


the operator telling him what to do next (i.e., remove a disk 

pack from a drive, etc.), since all commands in a DO file, 
including -the-comments, are displayed as the DO file is. ` 

processed. Finally, comments may be inserted in a BO file to 


make it. self documenting. 
Example: 
nr THIS IS A COMMENT 


A "wait for operator" can be inserted in a DO file (usually 


after comments telling him what to do) by use of a 


LIST CONSOLE: - 


command. The operator signifies he hàs completed the. : 


requested action by typing ^Z.. 
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 SDOSDISKINIT 


. SDOSDISKINIT is a utility program that. converts a ` 
freshly-formatted disk into a file-structured disk suitable. 
for storing and retrieving data from files. SDOS cannot 
place files on a disk until it has been. SDOSDISKINITed. 
SDOSDISKINIT can also be used to recycle a file structured 
disk whose format is good, but contains no useful. files. CA. 
formatted disk is one which the disk electronics can read; 
most disks come formatted from the factory, but the format 
can be accidentally (magnetically) damaged, thus peer 
re-formatting before the disk can be. usen) s 


: SDOSDISKINIT places the files BOOT. sys, DIRECTORY. se 


* DISKMAP.SYS, BADCLUSTERS.SYS, and a vestigial SDOS.SYS on a 
disk. It also allows the operator to- Specify a disk i 


identification, and to select a set of "tuning" parameters. te AE 


Optimize disk I/O for whatever applications that will be used 
. with the disk. SDOSDISKINIT will suggest values for the 

tuning parameters so that the dci need not understand 
them to use the program. 


The program is invoked by typing: 
. SDOSDISKINIT <diskdevicename> 


The Gievics spedita must be a disk drive. and must bo 
dismounted! (this usually prevents accidental 
SDOSDISKINITing of a good GEER Is. as it has probably been used 
and therefore mounted). l 


` The program LSSpOROA with its banners and the questions: 


*** SDOS disk initialization Vl.l *** 
Disk Id? 


The operator must supply a 32 character maximum disk 
identification to be used for this disk (this identification 
is printed on a FILES display or at boot time). If more than 
32 characters are enteréd, the operator is re-prompted and ` 
must type in a shorter disk identification. This disk 


identification may not contain a double quote DE? character. ` 


Next, the ‘expected number of files for this disk must be 
entered. SDOS will supply a hint, based on an average file ` 
size of 8192 bytes. The value entered does not limit the 
number of files on a disk; it is used merely to pre-allocate 
enough DIRECTORY. SYS space to allow quick location of file 
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names over the. life of the disk (without having to: E the 


directory; this expansion ruins all ‘the hashing). 


Next, SDOSDISKINIT asks: 
From what disk device can the tuning parameters be copied? 


There are two valid responses: a disk device name, or NONE. 
Giving a disk device name is the easy way out; all tuning 


parameters will be copied from the specified disk. Assuming 


another disk is mounted on the. System with the proper tuning, 


this is the fastest and safest approach. Note that the disk 


drive specified should be the same type as the disk being 
initialized; tuning parameters for a floppy disk are not 
appropriate for a 10 megabyte disk and vice- versa. ` 


If the operator supplies a disk device name, hen E No IM x 
SDOSDISKINIT will display the parameters reàd from the : 


Specified disk, and proceed with the disk initialization. 


If NONE is specified, then the operator must supply the 
tuning parameters himself. The program will request number 
of sectors per cluster (NSPC), minimum space to be allocated .. 
to.a disk file when it is created, "middle" allocation (how 
much to be allocated to a file being extended), and the map. 
algorithm. All tuning parameters are determined by educated 
guesswork and some experimentation; the operator may have to 
SDOSDISKINIT a scratch disk several times to test various f 
combinations of. tuning parameters. 


NSPC essentials determines the maximum DE of a file 
(ignoring the physical disk limitations). If NBPS is the 
number .of bytes per sector, the largest a file can be is (in 


bytes): 


eye ee 


A good value to choose for NSPC is one for which files are 
just barely large enough to cover the entire disk. PES 
SDOSDISKINIT suggests the unique value of NSPC appropriate 
for this. If files on a particular disk (like an 80 megabyte 
Storage module) do not need to be as large as the disk, then 
NSPC can be adjusted downward appropriately. Note that NSPC. 
must be chosen large enough so that no more than 65534 
(Logical) Clusters are required for a disk, where NLCN. - 


 INT(NSPT*NTPC*NCYL/NSPC). 


If program load time is to be optimized, either choose a 
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Small value of. NSPC (so that an entire cluster of the file 
can be loaded without dumping the header cluster of that file 
from the disk buffer pool) or a large. value (so that the 
header cluster is not often needed, and.so the cost to. 
refetch it to the pool is negligible). 


MINALLOC determines the minimum disk space (in clusters) 
allocated to a new disk’ file for this disk. Making MINALLOC 
large decreases the frequency with which the allocator must. 
add more disk space to a disk; it is a good idea to set | 
MINALLOC equal to the average number of data clusters in 
small file (SDOS always allocates at least the header cluster 


of the file if the file is not contiguous). "l"-should- be 
-used if no better value is obvious 18: is not a valid 
. MINALLOC). : Sa . 


.MIDALLOC determines how much disk endet do to be ue. d LU Y 

“incrementally added.to a file when it needs to grow. This 
value must be larger than zero! Use 1 if no better value is 

obvious. ; l E p 


MAPALGORITHM is used to tune rotational and seek tunes) 
Actual interpretation of the 16 bit number given here is » 
'completely up to the disk-sector-driver for the disk device e 
which contains the disk being initialized.  Commonly, the 16 ( 
bits are treated as a cylinder-to-cylinder seek "spiralling" 

byte and a Sector "spacing" byte (most and least significant, ` 
respectively). The "spiralling" byte defines the delay l 

(measured in units of sector times) between the last logical 

sector on track T and the first logical sector on track T+l,. 

and is tuned best when it is just larger than the actual . 
track-to-track seek time (this may also require accounting 

for head settling time). The sector "spacing" specifies the 
distance in time between one logical sector and the next 

(within a track); 1 indicates the LSNs are physically D 
adjacent, Most SDOS systems cannot pick up two adjacent LSNs 

unless they are spaced every other sector (spacing =. 2); 

optimal spacing is just slightly longer than the minimum 

amount of time to read a sector +6ms. . The MAPALGORITHM is 

usually printed and entered as a hex number (:xxyy). Once 

the Mapalgorithm has been chosen, SDOSDISKINIT proceeds. with 

the disk initialization. 
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pk User Only. wants to initialize a disk. 


. SDOSDISKINIT D2: 3 i 
*** SDOS disk initialization vi. 1 Wäi 


“Disk id? Sample init — 


From what disk device can the un ings parameters be copied? D3: : 
NBPS= 256 NLSN= 1232 NLCN= 388 NSPC= 4 MAP. ALGORITHM=:0209 
How many : files do you anticipate having. on this disk? 

(I would guess that 38 would be about ones 38 

Place disk into device and: hit return ^ - i 


a 


.* User. wants to change. tuning. parameters. 


 1SDOSDISKINIT D2: 


*** SDOS disk initialization vi. ] *** 
Disk id? Sample init 
From what disk device can. the tuning barama bas be copied? none 
O.K., how about telling me something about the disk... : 
How many sectors per cluster a suggest 4 )? 4 
MINALLOC: 1 hi I 

MIDALLOC: 1 

MAP ALGORITHM: :298 


 NBPS- 256 NLSN- 1232 NLCN- 308 NSPC= 4 MAP ALGORITHM-:8208 
- How many files do you anticipate having on this disk? ` E 


(I would guess that 38 would be about right): 60 


Place disk into device and hit return 


Notes about operation of SDOSDISKINIT: 


1.) SDOSDISKINITing the disk in the default drive works, but. 
leaves SDOS with a dilemma on completion; from where can it ' 
get a DEFAULTPROGRAM? For this reason, it is not recommended | 
to personm an SDOSDISKINIT on the default drive. | 
2.) The operator should insure that write protect on the | 


- chosen drive is disabled, that the inserted disk has already: 


been formatted, that TIME has been set, and that the chosen 
drive has been D S Ted before starting an SE 


3. ) Inobtaliation of SDOS. sys on a disk (SDOSSYSGEN) should pe. 


performed only immediately after that disk has. been 


~- SDOSDISKINITed. 5 "es 
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SDOSDISKBACKUP 


The BACKUP program. is used ës copy the entire contents of one 
disk onto another disk or to copy a subset of the files on ` ` 
one disk to another disk.  BACKUP verifies the copied: 
Gisk/files, and also provides for recovery from disk 1/0 ` 
errors (the COPY command does nose This section describes 

. SDOSDISKBACKUP Version l; 0. l ! E X E 


The two forms of the BACKUP command are: 
1) . SDOSDISKBACKUP [sourcedisk] TO destinationdisk- [USING MAPALGORITHM map#] 
“ 2) .SDOSDISKBACKUP [sourcedisk] copylist TO destinationdisk EXCEPT exceptlist 


where- ‘anything enclosed in square brackets is optional, i. e. E 
— [sourcedisk] means the source disk need not be í ana c 
~ ^is assumed to be the default disk if not present). "vue 


Form I: Disk (Backup 


This form copies an exact image of the source disk onto the 

destination disk. The destination disk must be dismounted 

before the Backup can take place. If a new map algorithm is L4 
Specified, the map algorithm of the destination disk is set y» ( 
to the specified map algorithm number; otherwise, the map : 
algorithm of the source disk is used. ` Thus, it is possible 

to "tune-up" an old disk by copying it. to a new disk under a 

better map ai Apei Shi: l : 


For example, 
.SDOSDISKBACKUP DØ: TO Dl: 


would make an exact copy of D@: on Dl:, writing over any old 
data on Dl:. l E 


-SDOSDISKBACKUP DØ: TO Dl: USING MAPALGORITHM :0304 


would have the same EE but the map algorithm used on D1: 
would be changed to hexidecimal 3804. n 


Assuming DØ: is the default disk, the above two Commandes 
could also be written as: l l " e 


KEE - .SDOSDISKBACKUP TO Dl: .. 
. and f i 
.SDOSDISKBACKUP TO Dl: USING MAPALGORITHM :304_ 
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Note: SDOSDISKBACKUP automatically ENEE 211 DISMOUNTS ` 
required and flushes buffers so that a 'DISMOUNT is not needed 
after completion (see COPY command). dus 


- Form II: Selective File Backup 


.The selective file Backup is T to. copy some of the files 
on a disk to another disk. The files to be copied are 

- specified by a "Copy" list.and an "Except" list. All files 
mentioned in the copy list are copied unless they are i 
mentioned in the. "Except" list. The lists are ass aR of a 
— list of filenames containing. wildcards (see Command. SES, 
Interpreter) and/or an optional trailing query (", 2"): 


filenamel, £ilename2,...[, ?] ^ m m d 


E meaning of the. query. changes. depending: on. whether dt. 


appears in the Copy list or in the Except list. If it is. 
present in the Copy list, it has the effect of asking the 
user whether or not he wants to copy any file not already 
chosen in the Copy list and not ruled out in the Except list. 


If the query command is present in the Except list, it has 
. the effect of asking on all files except those i; 
` ruled out in the Except list. : 


Following the Except list (the ‘destination disk if no Bkcept 

list) .may be the phrase AFTER dd/mm/yy. This will cause only 

files whose date is after that specified to be copied. - AFTER 

may not be used when backing up an entire disk. - 

Examples: | l 
.SDOSDISKBACKUP DØ: *.BAS,*.ASM,? TO Dl: EXCEPT JUNK. BAS. 


| Automatically copies all files ending in .BAS and .ASM 
(except JUNK.BAS) and asks about all others. 


.SDOSDISKBACKUP *. LPT TO MTB: EXCEPT IMP. LPT,? 


Asks about all files from the default disk ending in .LPT 
SE TMP.LPT, which it ignores). 


f SDOSDISKBACKUP D@:*.BAS TO Dl: AFTER GE | 
E . up only. ¿BAS files with a date of 2/15/79 or greater. 


ERROR RECOVERY 
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While copying, Backup may encounter Disk Read: or Disk Write d 
. Errors. Should this occur, the program will lead the user . 

through a series of procedures to recover from Or. to sidestep 
Che EE 
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SHUTTING DOWN 


To stop operation of the computer. under. SDOS, the operator 
needs to DISMOUNT all the disk devices (see DISMOUNT command. 
of SDOSCOMMANDS). This cannot be. (conveniently) done while a 


e program other than SDOSCOMMANDS is. running, so the operator 


must wait for any currently running programs to Stop 
execution or manually kill program execution via "CC, A 


turnkey system will have special provisions for. Shutting down 
and performing the required DISMOUNTS. I ` 


. The dismount commands are given to SDOSCOMMANDS; ` FAILURE TO | ^. 
 ;DISMOUNT A DISK WHICH WAS USED IN ANY WAY BY SDOS CAN MEAN ^ ^ ^ ^" 


LOST DATA (SDOS works hard to prevent this even if DISMOUNTS 
are not used, but the Scheme is not perfect). 


After dismounting all disk drives, the ` operator may push. 
RESET to cause execution of SDOS to cease. . a 


This ‘shutting down procedure must also be ‘performed if it is 
desired to boot from another disk cartridge or to obtain 


error messages from an ERRORMSGS. SYS file on a drive other ` 


than the one booted from. 


If an Error 1846 (Disk Write) occurs during a DISMOUNT, your 
disk is probably software damaged; certainly, some data has ` 
been lost. Run SDOSDISKVALIDATE immediately (before 

attempting to DISMOUNT again). If another Disk Write error 


occurs while starting SDOSDISKVALIDATE, just start it again. 


Keep trying until the SDOSDISKVALIDATE succeeds in repair ing 
your disk. , j 


An Error 1002 (File is Open) during a DISMOUNT indicates SDOS 
is a little confused; the DISMOUNT was successful in moving 
all your data back to the disk, but SDOS has its fingers 


glued to the disk. Ignore the message; but you must run 


SDOSDISKVALIDATE the next time you get a chance. 


If there is a software malfunction, and the operator cannot 
get SDOS to respond in any way, then SDOS has died and 
effectively shut down. This kind of "shutdown" will very 
probably software damage all the disks in use; use ne 
SDOSDISKVALIDATE Programi ‘on. all of them. 
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. DISASTERS, or ^ 


Js There are: “many 


as: expected, "Many: times this can happen le^ 
"Ehe operator. ot "some: ,SPparentiy. min I. itn 


pack, F ER Ze? system pach 


et to see puer We ao 


dead and you'need to re-boot). 


input to SDOS or application programs is done on a” 
the program, and return control to: DEFAULTPROGRAM. ` Killing ` E 


` something is wrong. IË- you: have to kill an application 
obtains no response, but does echo, and nothing happens, 
Tre- ‘boot; Fun the SDOSDISKVALIDATE Progra, 
. 4. ) "It said, i 
e the DEDI SKBAERUS program to copy the file. "(read “errors . 
Cause. ‘COPY: to: quit); then--run-the- -SDOSDISKVALIDATE. program. 


 SDOSDISKVALIDATE will find the cluster which caused the error 


"What do. I. do SE. 


— O Än 


Ls ) "SDOS won! At pa 


each disk * m try all the tercie je 


3. ) "It didn d EE "when. Is ked i 


but nothing seems to be happenin 
occurring, just be a little'pa 
^C, things. are próbably OK (if 


all, perhaps: 'the program is. waiting for “input; since most ; 


line-by-line basis, perhaps typing «CR» will help. /If-t : 
is still no response, try ^C^C. This. will cause. SDOS to. kill - 


the program may cause it to leave disk data” files contents, 
little confused, so don! t. do this. unless: “you're convinced . 


program, it. probably has a bug in it; tell ‘somebody,’ ’ Af; =c ` 
then `: 


there is also probably a bug; you will have to RESET and 


Finally, the contents of the data file need to be reviewed; 
since at least one sector's worth has been damaged. 
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and add it to BADCLUSTERS. SYS so it. cannot cause any more 
trouble. NOTE: FAILURE TO RUN SDOSDISKVALIDATE AND TO CLEAR 

UP ANY DISK FILE STRUCTURE ERRORS MAY RESULT IN A FILE SYSTEM 
"DISASTER AT A LATER TIME! e 


5.) "It said, "Disk Full'". Delete some old files You are ` u 
not going to need anymore and try again. e zoe 


6.) "SDOS Checksum ` failure". Either memory is beginning to ` 
fail, or (more likely), the application program just run has 

a bug in it which steps. on part of SDOS. You need to Sup e Ure 
. re-boot; if you were not debugging a program, it is time to 


kun a memory test. In any case, the SDOSDISKVALIDATE program 
¿should be ` run on all disks in use’ at the time of the error. 


7.) Power failure occurs.  Re-boot “and run. the 
SDOSDISKVALIDATE program on all disks. that were in drives at. one 
the time of power failure. l ; ; 
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EDIT 
, The SD. Text EDITor is EE by typing its name: 
nd ena | 
"It will identify itself, 
E EDIT V1.1 Copyright. (C) 1979 Software Dynamics 


and then accept commands. The user should select an input 
Tile wusing ER) and an output file o EN and E begin: 


Mur ur MAE 
x WEWPRIMES2.BASN ` 


-The line following the word EDIT is passed to: the editor as og 
commands; a quick edit can be done via: 2 


. EDIT ERPRIMES1. BAS\EWPRIMES2.BAS\1ACHELLO\BYE\EXIT<CR> | 
ASM a i | i C. 
The SD Assembler (MAL) is started by typing its name: | | 

-ASM 


It will identify itself, and then ask for Source, Listing, 
and Binary files. 


SOFTWARE DYNAMICS MAL/6800, Version dx 2/ 37E4 
Source File=DRIVER.ASM 
Listing File=LPT: 
‘Binary File=DRIVER.MIK 
|» f | 
BASIC . FK MEE 
: i d : bx l : 
The SD BASIC Compiler is started by typing its name: 

.BASIC ` | x eo SE e s ç. 


It will identify itself, and then ask for the name of the 
file to be compiled, and the name of an output file. 
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SOFTWARE DYNAMICS BASIC V1.3 
INPUT FILE = PRIMES2. BAS 
OUTPUT FILE = JUNK SR 
E COMPLETE 


The output of the Compiler: needs to be E EE The 
/' Assembled (MIKBUG) output may be executed by simply typing 


its name to the command nee ipe er, 


‘The Sañu e of the assembler is MIKBUG. ` E loaded 


(inefficently) directly by SDOS, or the MIKBUG can. be 
converted to SDOS Load Record Format by MAKEBINARY, and the. 


‘Load Record Format version loaded instead. 


MAKEBINARY 


MAKEBINARY is used Co convert MIKBUG format files to SDOS 


^Load Record Format. ` MAKEBINARY should be used on production 
programs (including complica BASIC programs) because Load l 


Record Format files occupy. less disk space and load faster 


than the MEBBUG versions. 


 MAREBINARY.is invoked by typing its name; 


. MAKEBINARY 


It will identify itself, and prompt for a MIKBUG input file, 
and a binary output file. 


MIKBUG INPUT FILE = PRIME.MIK I 
SDOS LOAD RECORD OUTPUT FILE = PRIME 
START ADDRESS = «CR» 


If <CR> is typed in response to START ADDRESS, the start 
address is set to that of the address of the first MIKBUG 
load record (this is automatically correct for compiled BASIC 
programs). Otherwise, a hex value must be entered; this 
value is taken to be the start address. ` ; | 


COMPILE | e EE 


NEM 
COMPILE is used to compile and usce a BASIC program | 
is easier than invoking the BASIC compiler and Assembler 


(this 


` individually). It is invoked by typing: 


_ COMPILE MYPROG.BAS | 
A BASIC Compile and assemble are automatically executed. 
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PIX ` 


FIX is used to EDIT and COMPILE a BASIC program. - It is 
canvoked Br typing: . | us M E 


ics «FIX ABC, BAS E 


(the extension .BAS is "Suportanti) FIX wili cause the ‘current 


- copy of ABC.BAS to be renamed to ABC.BAK (80 a backup "copy" 


is made), and then ABC.BAK is "EDIT"ed into ABC.BAS (FIX will. 
invoke the EDITor automatically). When EXIT. js typed” to. the - 


ae ieee COMPILE is S invoked... 
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 DBVICE- INDEPENDENT E 


SDOS allowe user. programs to. view alr disk files and 1/0 E 


. “devices as being fundamentally. the same, i. es, if one can i 
perform an operation on a device of type x (say, LPT: ), one I 


can generally perform: that same operation on a different : 
device of type Y. : . , 


In this. section, a conceptual model of hee “Elles /dévices : | 
should act is presented (later Sections describe. in detail 


the. system. «calls. 'used to implement: this- model)-.--SDOS is: 


designed in such a way that disk files conform to. this model. 
very closely; exceptions will be noted later. Real devices 


Such as line printers, CRT's, Digital-to-Analog converters, 
zovete., are made to emulate this model.as closely as possible ri, 
via a device driver routine in the 1/0 package} the degree: of E uo 
“closeness depends entirely on this driver. In many cases, it 


is not practical or appropriate for a device to match the 
desired model; this means that there are device-dependent 


+ (actually, dr iver-dependent) e on this device 
independence. 


ein 


“SDOS implements files for the purpose of. storing and 


retrieving data. A file is assumed to consist of a 
sequential set of 8 bit data bytes, with the first byte being 
numbered zero, the second being number 1, the nth. being 
numbered n-l. Each file has a size, which is equal to the ` 
number of bytes of data stored in the file. The data in a - 


"file can be read or written sequentially in variable-size 


blocks. If new data needs to be added to the end of a file, 
the file can be automatically extended. Commands exist to 


allow a file to be positioned to a specified byte position in 


preparation for a later read or write operation, thus 
providing random access. Data can be read or written in pure 


binary, or in ASCII ds format. 


“A device is (usually) a physical piece of hardware capable of ` 


retrieving and storing data, converting data to/from printed 
form, etc. ` (some devices, such as the CLOCK:, are almost 
purely software). In many cases a device is treated as a 


file by SDOS. Some devices can actually store many separate 


data files (such as a disk device). 


“I/O channels are the method by which.a user program indicates 


which file, and where within a file, that a data read or 


. write is to occur next. Each I/O channel is given a number, 
zero being the lowest. Standard SDOS systems have at least 


eight I/O channels per user program; some 32K systems have 
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only 4 1/0 channels. 
EN Virtüally all Sper at ines on a file must ` be E in 
conjunction with an I/O channel. An initial connection is 
established between a user-program specified I/O channel and 
. a particular file by use of a SYSCALL:OPEN (or 
.SYSCALL:CREATE). All further operations on that file must 
Specify the operation desired, and the I/O channel number ` 
associated with a file.” Note that a particular file may be 
open on several I/O. chànnels, thus causing interactions ` 
between what appear to-be independent operations. ` The ^ 
“association between a channel and a file is broken with a: 
-SYSCALL:CLOSE operation; a channel on which this operation is 
the. most, recently. executed valid operation is said to be | 
CLOSED. Mo “operations” “except OPEN Or CREATE are valid. ¿on a 
closed 1/0 channel.. 


The I/O channel has associated with it several pieces of 
information: whether that channel is open or closed; the 
particular device driver which is responsible for that file; 
m f information selecting which file on that device is to be 
E used; data selecting a position within that file; and a 
column count (next print position on a real or simulated 
printing device). 


When a file is first opened, the position is reset to zero 
(beginning of the file). Each read or write operation on an 
I/O channel advances the position for that channel by the 
amount of data read/written. An End Of File condition is 
said to have occurred whenever the file position ona 
particular channel is equal or larger than the file size (in 
bytes). Note that two I/O channels open to the same file are 
not asss HY positioned to the same Prete within that 
"file. 


A column count is maintained for. the purpose of "tabbing" (a: 
text concept). This column count is zeroed whenever binary 
data (non-text) is read or written to a file, and adjusted to 
reflect the position of an imaginary typewriter EE 
textual data is copied to or from a files : 


Operations defined on files include, but are not limited to: 
OPEN, CREATE, “CLOSE, DELETE, RENAME ` 
READA, READB, WRITEA, WRITEB, . CONTROL, STATUS 
POSITION, GETEOF, GETCOLCNT 


. Other operations are device-driver specific. 
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(device) that already exists, for the purpose of reading (or | .. - 
updating) data in that file. Data-input only devices such às . ^ ^ 
. paper tape readers must be OPENed in order to read data. .All +... 

devices can be OPENed so that the device type is easily read 
„without knowing the kind of device being OPENed.. Sur me 


OPEN is intended to associate an I/O channel with a file 


CREATE is intended to associate a file or device with an I/O te 
channel which is to be used whenever an entirely new stream ^  "  - 
of data is to be written or stored. . In particular, when a = 7 
new disk file is needed, or data sent to an output-only |. . 
‘device (such as a line printer) a CREATE should be performed. 
Some devices, like CRT's, which are both input and output, ` 
^ can be either OPENed or CREATEd. D MIT. A 


1/0 channel, and to cause the driver for the device on which |  - 


that file resides to finish any operations on that file. 


DELETE is used to delete (disk) files from devices that store 
multiple named files. Devices cannot be deleted. Once a 
file is deleted, it cannot be OPENéd and its contents are. 
‘permanently lost. | | e 


RENAME is used to change the name of a disk file, and is 
illegal when directed specifically at a device. 


READA and WRITEA are used to read and write ASCII (textual) 
data. This is used to read data from consoles, print on line ` 
printers, etc. If a file has no more room for new data l 
written, then the file is automatically expanded. A channel ` 
number must be given to select the desired file. ` f SÉ 


 READB and WRITEB are used to read and write binary data to 
and from devices (data stored in a form convenient for the 
computer). An I/O channel number is required to select the > 
desired file. Some devices, like Digital to Analog l 
converters, can only perform Write Binary. 


CONTROL operations are used to cause device-specific 
operations that do not fit into the above types of |^  . 
Operations. ‘Typical control operations are GETTYP (get ` 


device type), POSITION, DUMP BUFFERS, etc. 


STATUS operations are used to read device or file specific. | 
data. Typical status data is DEVICE TYPE, FILESIZE, EOF flag 
and COLCNT. — o ` SE "m: x | : 
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geen / is used to "Change the piace. in the file that the. 
/. ..7 . next read or write will start transferring data to or from. 

¿POSITION affects an I/O channel, not the file itself, so. 
Several I/O channels may be positioned to different points in 
the same file. A file can be positioned anywhere past. the 
last data byte; this is used to Sapang a file. 


GETEOF is used to decerudhe if the position of à Patticuliure ieu 
Cile is at or past the, file size. ALL €., there is no more: data 


T cols is used to: Pesa: back ro sinilated print. head. 
` position of an ASCII text file (or an actual print head 


ular: ‘display is desired. Like the. file position, this. 
value is 1/0 channel dependent. 
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position for a line printer, etc.). This is useful when E 
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DEVICE DRIVER CHARACTERISTICS | 


i This Section describes. ‘the actual characteristics. of the 
“device drivers, and how operations on these drivers differ 
from an "ideal" E vane es (as described under DEVICE- ENDEPENDENT 


1/0). 
; These characteristics are observable EE by thé assembly 
.lafiguage programmer via "Syscalls". Many features of the i 


device drivers may be. masked by a high level: language. such as. 


BASIC; to use. these. EE an escape. to AE ue Aanguage. MEN 


may be required. 
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DISK File Driver 


: Disk files ander spos implement virtually all aspects of I 
general file handling: as described under Device- Independent: - 
I/O. This section details exactly the operations implemented ` 


by the SDOS Disk File Driver. 


An SDOS disk: file can physically contain as: ‘few as zero: data. 
bytes, and as many as the remaining free space after an: 


SDOSDISKINIT.' SDOS. keeps track of disk file sizes accurate ' 


- to the byte.- Apparent file size may be much larger than the. 


actually allocated disk SDRCSE such a file is said to be 
"sparse". : RII VD 


"Disk files may be allocated "dense"ly or. "sparse"ly. ` A dense ` ` 


file is one in which data clusters are allocated for each ` 
data byté whose position is less than the file size. A 
Sparse file may have a position (with a smaller value than 
the file size) for which no data cluster is allocated (data 
read from this area of the file appears as zeroes). 


An OPEN is used to open a disk file (that must already exist) 
for reading and/or update. If the file does not exist, an . 
error will occur. A CREATE will CREATE a new disk file which 
will supersede the old version of the file when the new. file 
is closed. The new file will contain zero data bytes after 


“creation. A new file cannot be created if the old file is 
 Gelete or write protected, or a new file by that name is 


being. created. 


Any OPEN or CREATE that specifies a filename that does not. 
contain an explicit device identifier will be automatically 
assumed to be a disk file on the default disk (DISK:). Also, 
any filename that is prefixed by a disk device name, and does 
not consist solely of the device name is assumed to be the 
name of a disk file on the ADC SUELOS disk. 


For the form of disk file hanes, see the section on DEVICE 


“and DISK FILE NAMES. Disk file names may include a 
_ parenthesized integer; this integer is used by CREATE to 
allocate enough disk space at file creation time to contain: 


the number of data bytes specified by the integer. . This has. 


two advantages: first, it decreases the amount of time needed p 
to allocate the space to the file (it is cheaper to allocate 


all at once than to allocate. several little pieces when SDOS 


discovers it needs them) and it increases the probability the ` 
.allocation of the file on the disk is contiguous, which ` 


decreases random access time to the file. No error is given 
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if there is not enough disk space to satisfy the request. 
OPEN will parse but ignore the size. +  - i 

If CREATE is used to make a new disk file, and there is an 
old file by the same name, the old file must not be delete or ` 
write protected or an error will occur and the new file will 
not be created (nor will the channel be opened). Also, no 
file by that name may be’ CREATEd simultaneously (i.e., in 
psuedo-BASIC, I Ex ense d 7: 


CREATE #1,"X" 
° CREATE $2,"x" SC 


will result in an error), Otherwise, the new file is |. 
created, and the channel is opened. As long as the newly ! 
created file is still open on the channel on which it was ^^ 


‘created, that new file is in the state of "being CREATEd". ^ ^ ^77 


If an old file with the same name does exist, an OPEN SYSCALL ` ` 


executed after the CREATE, looking for the same file, will 


open the old file. If the system crashes before the new file — 


is closed, the old file will be unaffected in any way. Even 
after the new file is closed, channels still open to the old 
-file will not notice any difference. When the last channel 

OPEN to the old file is closed, the space for the old file is 
returned to free disk space. l 5 : E ; 


Example: l 
TIME | OPERATION De ACTION 
1 E OPEN #1, "ABC" Opens old ABC 
2 l CREATE $2, "ABC"  .. CREATES a replacement 
3 OPEN #3, "ABC" Opens old. ABC f 
4 CLOSE #2, "ABC" : Marks old verson of ABC 
l p E as deleted E 
5 f OPEN #4, "ABC" . Opens file generated at 
m ER f l time 2 i 
eg CLOSE #1,#3 — Deletes old ABC 


CLOSEing a disk file causes changes to the file size, 
protection, and other characteristics to be updated on the 
disk. If the system crashes while the file is open, these 
Changes are lost (not recorded in the directory). If the 
disk file is newly created, and is not replacing another by 
the same name, closing will make its name appear in the 
directory. If the file is newly created, and it isa | 
replacement for a file that already exists (i.e., one.by the 
same name), then the new file will replace the old in the 
directory, and the disk space allocated to the old file will 
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be. returned to. “Gree Space as-soon as no other I/O channels 
„remain pen to the old version of the etes 


RENAME is 


“used to han s the name o£ a aren file. RENAMEing 


a disk file. to its own name is legal, and can speed up later 
- OPENS. of that file since a rename causes the file name to be 


' re-hashed 


into the directory. Refer to hash-lookup 


description of files. `A disk file cannot be renamed if it is 
write protected, or a file by that name already ERI SEES or a- 


DELETE is 


ce new file, by that name is being created, 


used ‘to free the space being used by a disk file 


and remove the filename from the directory. A file cannot be `` 


‘deleted if it is delete or write protected, or if a new 
version of the file is being created. 


CREADA ‘performs: exactly a ás “specified by SYSCALL: READA. > 
READAing through a large, sparse portion of a file may take ` 


-an excessive amount of time due to the automatic suppression 
Of all the zero bytes found in the sparse area. WRITEA, 
 WRITEB, and READB match the SYSCALLs exactly. If an error 
. occurs during a read or write, the file position may not be 
ES advanced properly. 


CONTROL operations available on disk files are the following: 


CC: POSITION As specified by SYSCALL definitions 
CC: DUMPBUFFERS is a no-op. 


' STATUSes obtainable from a disk file are: 


SC:GETPOS 


SC: GE POOL” 


Read position of file. 


Gert file column number. This value is zeroed by a 


CC:POSITION or READB/WRITEB and adjusted as data 
bytes are read or written in ASCII mode. The value 
of the column count at a. particular point in.a file 
thus depends on the last operation of a file; it is 
intended only for use with eeduene tet. ASCII reads 


. and. writes." 


T.a SOI GETEOF ` 


Rotura BOR Aik flag. EOF is set if positioned at 
or past file size. EOF also set when last byte of ` 
file is read or overwritten, or file is extended. 


EOF is reset when file is positioned with a 
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CURE a A positioning value less than the file size. 
Returns device type of DVTYP.FILE. See. 5 
SDOSUSERDEFS.ASM. All devices (drivers) are able 


SC:GETTYPE 


mie us iur S SS to return a device type. 
an - SC:GETFILESIZE | : E "ep. auct ceu t m Duo 

A © Returns the position of the last data byte written ` 
to the file, plus 1. | Scd uu ud 


Returns data about the file, such as sector size in 


-Returns the 24 bit LSN of the last sector which ^ 
Could not be read, written or located by the. disk 
Sector I/O driver. A value of :FFFFFF means "no 
bad LSN". Reading the LSN, changing the Map ` 
Algorithm for a drive, or dismounting a disk caüses 
the last bad LSN to get reset to :FFFFFF. 


x E Ger ca Hy 
^ Ne other status is obtainable from a disk file; 


. SDOS will allocate data clusters to a file automatically 
-- whenever a write request to a non-allocated part of a file 
occurs (it does not allocate from the current end of file up 
.to the point of the write; it simply leaves that part of the 
- file sparse). A cluster allocated in a formerly sparse part 
of a file is automatically zeroed to preserve the "zero" 
property of the pàrt not modified. f 


SDOS attempts to allocate data clusters contiguously (with 
respect to Logical Cluster Numbers) to minimize scattering of 
“the file over a disk and to minimize sequential processing 
^ time.. If absolutely contiguous allocation is not possible, 
.SDOS allocates the closest free LCN that starts a contiguous 
block of BOOT:MIDALLOC free clusters. x : 


I , . The SDOS disk file driver keeps track of OPENed (CREATEd) . 
LL files via File Control Blocks. | FCBs are in one-to-one 

; ~. correspondence with open files (not channels), and contain 

what amounts to a DIRECTORY.SYS entry. In particular, the 

-FCB-holds-the amount of disk space allocated to a file and 


dts apparent size. If a file is extended on one channel, the 
co extension will be apparent immediately on a different channel 
op which that file is also open because of the shared FCB. ` 
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Disk sectors are kept ` in a pool of sectors to minimize disk 
. reads of frequently accessed data. Data written into a file 
- will be immediately available through: another I/O channel on 
-which that: file is. open. because the (modified). disk sector in. 
- the pool is shared. Modified sectors in the. pool are. written 
back to the disk as space is required to bring in another 
= disk. sector according to a Least. Recently. Used discipline. 
The oldest: sector on. the queue will be written back. if its 
.. disk is free. .— E: 


These side effects: of the FCBS and the disk sector buffer 
DON, e : pool are subtle but desirable because it is appropriate that 
mw un TES different programs” “be able: to share a file and its contents 
m9 s exactly as it is-in any instant in time. Many disk operating 
systems do not provide this exact sharing capability, and 
a consequently make it hard to build a set of programs. that. 
7 interact. through: à “common data. base. p rM 


SDOS optimizes sequential I/O to. disk files "via "roadosheid*s 
- Whenever data from a particular sector of a disk file is 
fetched, SDOS pre-reads the next sector of that disk file 
into the sector pool. The read-ahead happens in parallel 
m with processing of data from the first sector.. This scheme 
TS . decreases sequential file processing time, and lowers the 
^. cost of reading records that span sector boungar ies to an 
acceptable level. 
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“DISK Device Driver 


“The SDOS disk device driver Ee access to the entire 
contents of a disk as though it were a single, large file. 
This facility is generally only used by utility programs to 
initialize, check out, and repair the file structure on a 
disk, but it may also be used to squeeze out the last ounce 
of available disk space, to cut down access time to a large 
file, or to read/write disks compatible with. the drive. but 
.intended for other disk operating sS ens 


“Disk device drivers may also be used to perform operations on 
"the. device. neseli; Such: as to dismount | a disk; c sos 


A disk device driver is OPENed when SDOS is “asked to OPEN a 
file whose name ‘consists only of a disk name. 
"A disk device” which" has been DISMOUNTed | recently i will Have a 
Map Algorithm of :0001. If the disk device is already 
mounted (i.e., has been used for disk file operations), then 
the map algorithm will be that given by the BOOTS SYS file, on 
the disk. : 


The disk device driver treats CREATE calls exactly like an 
OPEN. 


a 
Y 


CLOSEing a disk device simply dissss3ol apes the I/O channel 
number, and otherwise does nothing. I 


RENAME and DELETE operations directed to a disk device will 
cause an error. 


-READA and READB act as described under SYSCALLs; the contents 
of the disk are treated as a single, large stream of bytes. 
WRITEA and WRITEB act as described (once enabled by 

CC: UNLOCKDISK), however, a disk device cannot be "extended" 
when more space is needed, so writing off the "end" of the 
disk device will cause an End of File error, and the written 
data will be lost. 


| Access to sectors may be obtained by positioning a disk 
device to a byte position which. is a multiple °. the sector 
size for that disk. i I ! 


— 
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Disk device drivers support Rue following CONTROL ‘operations: 


cc: POSITION 
SS To position. for later reads/vrites. 


CC: DUMPBUFFERS I e. 
"This control operation will cause all modified 


Sectors belonging to the disk to be written back to 


it. It will also cause information changed in FCBs 
.of files open on that disk to be written back, 
Information in FCBs for newly created but not yet 
.; Closed files is NOT written back to the disk. This 
-ois not a. Substitute for a DISMOUNT control... KR 
operation. No parameters are needed. S 


LL. . QOSUNLOCKDISK- 


uu e qe erie -WRITEA “and. WRITEB to. work. oe ope ER on. ve 
seeeees co cum dusk ‘device. If CC: UNLOCKDISK is not. issued 0 > l 


after OPENing.a disk, and prior to a write, a. "disk 
is software write protected" error will occur. 
Requiring this control operation to write on the 
disk device prevents accidental writing to a disk 
: ; device. CLOSEing the disk device re-enables the 
eer oo. write protection. No psrencter® are needed. 


ee: DISKMOUNTDISK 
This is used to make SDOS let go of a | disk entirely 
so it may be removed from the drive. An implied 
DUMPBUFFERS occurs. If there are any (new or old) 
disk files OPEN on that disk, an error will occur 
and the dismount operation will not take place. 
-The disk sector I/O driver will be called so that 
it may physically eject the disk or perform other 
needed cleanup. A successful dismount also turns 
Off the FORMAT mode switch in the disk sector I/O 
driver. The map algorithm is et to +0001 if the 
dismount succeeds. 


‘ce: SETMAPALGORITHN - 

This allows the 16 bit Map Algorithm for khe disk 

to be changed. An implied CC:DUMPBUFFERS occurs 

t dis NO E ss . first; if there are any disk files OPEN on that 

—— 8907 5 0.2. 04. disk, an error will occur. If any error occurs, 

rag the map algorithm will not be changed. The map 

algorithm is d, in the WEBDE of the Sterne 
“block. ` à E = 
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CC: FORMAT | ES RM LN 
= €C:FORMAT-is used to switch into "blind write" 
mode, intended for disk formatting purposes. See 
Disk Sector I/O drivers. This era may not be 
available on. all disk devices. U e e 


E other CONTROL code is simply passed by. the SDOS Disk 
Device Driver to the. Disk ` Sector 1/0 driver. for its use. 


_ STATUS information obtainable from a disk device is the 
preblorings . ' > . 


"gei /GETPOS ` eeh 
ES As described under SYSCALLs 


— EEN | de c po ee 
loq los, ere dedita ta As described under SYSCALLs. tus QN A RES 


"SC: GETEOF | | 
I As Get under SYSCALLs — 


SC:GETFILESIZE cox f s : 
de : The size of the "file" that a disk represents is 
: Aus equal to NBPS*NSPT*NTPC*NCYL (the product of the 
sector size in bytes, and the number of sectors on 
the disk). Me S WM l 


SC:GETTYPE . 
Returns DVTYP.DISK 


BIO 'GETPARAMS 
Returns NBPS nümbér of bytes per ——: NSPT 
(number of sectors per track), NTPC (number of 
tracks per cylinder), and NCYL (number of 
cylinders) each as 2 byte values. See 
-SDOSUSERDEFS.ASM for details on format of result. 


SC: GETLASTBADLSN 
Returns the Pass s Sector Number of the disk. 
. Sector which last caused a Seek, Read or Write 
error. The LSN is returned as 3 bytes; an LSN of 
:FFFFFF means "no bad LSN". Executing 
SC:GETLASTBADLSN, CC:DISMOUNT, or CC: MAPALGORITHM 


causes the value to be reset "to no bad LSN", This - 
STATUS is. intended primarily for use by. TE 
SDOSDISKVALIDATE. ` 
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: The CONSOLE: ¿Device Driver 


e. CONSOLE: driver: implements ne SDOS 1/0 facility. For the 
_local operator's console. It provides keyboard entry, line 


input editing, and text display functions. The CONSOLE: 
driver also provides a standard method of dealing with cursor 
positioning, thus making screen-oriented applications useful 
on a wide variety of CRT display terminals. 


The CONSOLE: "driver presents an indefinitely. long input or 


NEUE: ird stream for. a program: 


“Tt may be OPENed or - CREATEd using the device name "CONSOLE:". S 

Doing an OPEN or CREATE resets the tabs to 8, 16, 32 .... Up 

^to 132. ` CLOSEing the console has no effect except to. l 

disassociate the I/O channel from the driver. CONSOLE: may . 
be open on several channels; output display by the console is 


exactly what would be seen if the I/O requests had been gt 
directed to one channel in the same order. 


‘RENAME and DELETE operations are illegal. 


READA| and WRITEA are the normal I/O modes used with the 
console, and match the SYSCALL specification. A READA causes 
characters to be taken from an input line buffer maintained 
by the driver. When the input line is exhausted, and a READA 
is issued, the driver processes characters from the 
type-ahead buffer, placing regular keystrokes in the input 
line buffer, performing editing as directed by control Keys, 
and performing echoing for the operator's benefit. A “Z read 
from the type-ahead buffer.will cause an End of File 


` condition to occur. Parity is stripped, leaving only 7 bit 


ASCII) codes. If this READA is not line mode, then multiple 
lines| may be entered and corrected before the READA will 
complete. Characters are not taken from the input line until 


«CR»? is typed by the operator. . 


When a. ' READB is issued, characters are taken from the 


remainder of the input line until it is exhausted, then 


characters are taken from the type- -ahead buffer. No echo or 


-character processing of any kind is performed. The exact key 


codes generated by the console hardware are Pa EE 
to the user software including the Ge bit. 


< If the. last ead. directed to the console was READA, then the. 


control keys “A, ^C, ^D, ^P, “Q, ^S, ^T, ^V, and <ESC> cause 
various switches to be set or cleared within the driver. at 


Che moment they are typed; these keystrokes are not passed to 
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.the user program. If READB was last issued, no special 


interpretation. of any keystroke is made; all keystrokes are 
placed in the type- ahead buffer for ‘processing. by the” user. 


WRITEA causes e output to the E i l 
characters are expanded. according to the tab table. <CR> ... 


characters cause a line feed and a variable number of idle 


characters to be output after em: Control characters are 


ER GE as “c (c = character). 


WRITEB causes the bit patterns to be sent to the console ` 


— exactly as “specified. in tne write: buffer. No <LF>s or idles | 
“are. inserted. 


D CONSOLE: supports the “following console operations: 


CC:POSITION ` i i : 

For CRTs, the EE information is. — as. 
a cursor position of the form R*256+C, where R is 
the desired screen row (Ü being the top of the 
Screen), and C being the column number (8 being the 

| Ietunost column), : ; l 


CC: DUMPBUFFERS I 
This is a no-op since the driver dumps characters 
to the console as fast as it can. No parameters 
are needed. 


CC: ECHO pe » 
This enables echo on READA. No parameters are 
needed. E 

CC:NOECHO f | 

i CC:NOECHO shuts off echo on READA. No parameters 
are needed. . . f ` ! 

CC:IDLES | Sage, = | 
This sets the number of idles to be transmitted | 
after a line-feed. The WRBUF holds a single BYTE 
value for Ene idle count. f g is legal. | 

CC: TABS | 


This sets tabs for tab simulation. The WRBUF must ` 
hold a string of bytes, each byte specifying the 
next tab stop. Each successive byte must contain a 
column number larger than the previous one. When: 
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the CONSOLE: is first opened, tab columns are set 
every 8th column, up to 132. e. 


Status obtainable from the CONSOLE: ` Ss FI MT 


Reads cursor position in same form as CC:POSITION. 


Returns the output ‘column number. Zeroed by binary 
weeds) updated on input. |. x. E n : 


: “Returns 1 iF “Z was recently seen while in READA ` 
M mode, and input line is empty. Otherwise retürns 
£.: EOF flag is never set if. the most. ‘recent read | 

was READER. e d e 
SC: GBTTYPE 
SE Returns DVTYP. CONSOLE 


SC: GETPARAMS 


Returns width (1 byte) and depth (1 ERG of 
‘console screen. Depth = Ü means continuous feed 


paper device. 
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. The CLOCK: Device Driver 


o e Phe CLOCK: device is used to set and read the current time 
Eus ;. and date. Since its function is limited, so is its 
"conformance to: the SDOS file concept. A Se 


“Phe CLOCK: device can only be OPENed. CREATE, RENAME, — 

DELETE, WRITEA, and CONTROL operations are illegal. CLOSE 
¿> does nothing except to disassociate the aS channel from the 
driver. 


A READA EE to the CLOCK: device returns a string of 17 
bytes. in, the. . following. form: 


HH: Ms SS MO/DD/YY . 

where HH is hours on a 24 hour GE MM is minutes, SS is ! 
Seconds, MO is the month, DD is the day number, and YY is the 
Mear modulo 100. " 
A READB returns 6 bytes exactly in the following form: 
T T T M D Y 


1p . where T T T is a 24 bit binary value equal to the number of 
en ` .1/680 second clock ticks since midnight; D is the day, M is 
the month, and Y is the year modulo 100, all in BCD. 


A WRITEB must write exactly 6 bytes in the format read by 
READB, and is used to set the time of day. ` 


The only status syscall accepted is SC: GETTYP, which returns 
DVTYP. CLOCK. 
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The LPT: Device Driver. 


o Tn d LPTs. device: ariver.. is used to Print. on the local printer. = 


ae allows only. sequential write. ASCII’ EE 


sou Te: LPT: always represents a new EC so. it miet be CREATES 
(not OPENed). CLOSE. simulates a CC: DUMPBUFFERS ;. and then. 
ee the. 1/0. channel and Che drivers: I SE a? 


RENAME, DELETE, READB, READA, and. WRITEB are not legal. A 
~ “WRITEA causes Che: "WRBUF to be printed on the printer. 


: Causes “any partial line to be printed as a “complete 
dine. ` 


Sets tabs for tab simulation. The WRBUF must hold 
a string of bytes, each byte specifying the next 
tab stop. Each successive byte must contain a 
column number larger than the previous one. When 

f E KE the LPT: is first opened, tab columns are set neie 
ERN MAN I 8th column up to column 132. 


STATUS obtainable from the LPT: driver is; 


SC:GETCOL 
Returns the column Amber at the current print head 
location 


SC: GETTYP 
‘Returns DVTYP. PRINTER 


SC: GETPARAMS ; ` : i 

Returns one byte of width (how wide the paper is 
measured in. characters) and one byte of uda) (how 
deep the Paper is measured in lines). 
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o0 Programs running under. $D0S communicate with- it via System E 
i ¿calls (SYSCALLs). A SYSCALL is a subroutine call (from the 

- -user program to SDOS) with a parameter block e the 
; function to. be performed. z E Ñ l East 


nies section: describes. the general philosophy. behind: the 
a "SYSCALLs and their general format. It assumes some knowledge 
of assembly language. S l ; i 


The most general form of a SYSCALL contains a fonction Code, 
me fixed. .needed. by the function,. .a..(pointer. to) 


.. . the SYSCALL causes the specified function to be performed 
according to the parameters, using data from the write ` 
buffer, and. storing a.result in the reply buffer. Many 
readers will. recognize. this as an EE of: š 


RDBUF:= F (PARAMS, WRBUF) 


The purpose of constraining all SYSCALLs to this form is to 
: simplify the process of transmitting a request from one l 
E. computer to another, with an eye toward future networking. 


Conceptually, SYSCALL execution proceeds as follows: 


-1.) The user program issues a. SYSCALL. l 
2.) SDOS transmits’ the. function code, the parameters, and the. 
conténts of the WRITE Buffer room the user's computer to some 
: target computer. ` 
Ex The target EE processes the SYSCALL and produces a 
reply. . 
4.) The reply, along with any error information, is. sent. back 
to the SDOS which sent out the request. 
5. ) SDOS places the reply in the user program" s reply buffer. 


ah a: carsndeslone Evade, the target: computer and the user's 
computer are one and the same. 


.. The primary advantage of this scheme is that by forcing all 
,'SYSCALLS. to have a fixed form for transmitting, performing, ` 
and receiving replys to function requests, the software logic 

. processing the request can forward it to another computer 

PO tap. ee near having a lot of function-specific knowledge. In 

——particulary-it-means-that the-forwarding logic need not -be ` 

“changed even when new functions are added to.the list of 
M 5 SYSCALLS. . 
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» Typical SYSCALL functions are: OPEN file, READ byte stream,- pues 
LOAD a program, etc. Not all functions require write data . 
^ ccXdvery a STATUS Syscall needs only the function, some ^-^ ^ 
.' parameter bytes and a reply buffer); nor. do all functions ` 
.return a result (WASCII writes a string of ASCII bytes to a 
=: file and returns no result). Some functions have neither- 
“write nor reply buffers (i.e., EXIT to system). Furthermore, 
"many. functions: have: mide Ee (like ‘CLOSE! I/O- ee 


SYSCALL . eege 


> following definitions give the formats of a SYSCALL block. 


IM SYSCALL BLOCK DISPLACEMENTS 


k 
T E ORG. E ud. EE 
SCBLK: OPCODE ` RMB... 1 ` PRIMARY SYSCALL FUNCTION 
q ; ' (OPEN, READ, ETC.) 
 SCBLK:WLEN RMB- 1 WAIT FLAG BIT (Ü-WAIT) AND 
SE U i = SYSCALL BLOCK LENGTH (@..127) 
SCBLK: PARAMS RMB 2 PARAMETER BYTES TO OPCODE ` 
= EEN |. ^ (SECONDARY OPCODE, CHANNEL +) x 
-= = -~SCBLK:WRBUF RMB . 2 POINTER TO WRITE DATA BUFFER € 
^^ SCBLK:WRLEN RMB eer er NUMBER OF BYTES IN WRITE DATA - 
U . ` BUFFER ` : ! 
SCBLK:RPLEN RMB 2 LENGTH OF REPLY (RESULT OF 
E SYSCALL) 
SCBLK:RDBUF RMB — 2 . POINTER. TO READ DATA BUFFER 
f (WHERE RESULT GOES) 
SCBLK:RDLEN RMB ` 2 CEILING ON SIZE OF REPLY 
(READ DATA BUFFER) 
SCBLK: DATA RMB 0. ` OTHER PARAMETERS FOR SYSCALL; ` 
i | UP TO 127-14 BYTES 


PERDR TEND RMB g "^ END OF SYSCALL BLOCK; ASSERT : 
Š> LENS _ i SCBLK: WLEN[1..7] -SCBLK: ENDS CELE: OPCODI 


SCBLK: OPCODE is the desired function, and occupies a “single 
. byte. Legal functions under SDOS 1.9 are shown in table 1. 
= (Definitions of all values for SYSCALL opcodes and related | 
. L information is given in the SDOSIOPKDEFS. ASM oon in. the. 
back of this manual): zx END. AN 


| SCBLK:WLEN is a single byte with two parts: a Wait flag (the 

= most significant bit) and a LENgth (2 to 127, measured in - 

|. bytes) (the SYSCALL block length). “he wait flag is intended 
` to allow overlapped READ and WRITE operations to files, but. 
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..is not implemented in SDOS 1.0. When this bit = Ø, it means 
wait for operation complete before returning control to user 
.. program". "1" means "don't wait". To retain compatibility. 
¿With future releases of SDOS, the user is advised to leave 
this bit reset (8). The LEN field specifies precisely how 


"long the SYSCALL block is. Each opcode requires that this. 
. byte have some minimum value, or the SYSCALL will be aborted. |. `` 
.The LEN field is used to determine how much data must be sent M 


to another computer. The LEN field can specify more bytes . 


-. than actually needed by the SYSCALL without ill effect, but. 
Processing. the unused bytes may. increase the execution time.. 
Of the SYSCALL. ` A11 SYSCALLs have at least the SCBLK:OPCODE 
"and.SCBLK:WLEN-bytes.- " D ¿4 oe ae aL 2 b í. 


 SCBLK:PARAMS are 2 bytes used for sundry purposes as . 
` parameters to the opcode requested. Three cases are of . 
particular note: first,.one of the two parameter bytes is - 
- generally used to hold an I/O channel number on I/O-oriented 
= SY¥SCALLS. Second, a parameter byte may contain an opcode 


extension byte, as with the STATUS and CONTROL SYSCALLs; the 
parameter byte selects which control function is to be 
performed or the particular piece of status information to 
read back. The third case is some 16 bit number, such as 
passing an error code to SDOS via the SETERROR SYSCALL. In 
no case may these two bytes contain a pointer or any other 
kind of reference to other data in the memory of the user's 
computer; only data values or relative references to data in 
the write buffer or the SYSCALL block itself are legal 
(because after the SYSCALL has been sent to another computer, 
how could we follow a pointer?) SCBLK:PARAMs need not be - 
included in the LEN count for SYSCALLS such as SYSCALL:CLOSE, 


SYSCALL:EXIT, etc. : 


SCBLK:WRBUF and SCBLK:WRLEN define the starting address of 
the write data buffer, and its length in bytes. SCBLK:WRBUF 
contains the address of the first byte of the buffer; 


SCBLK:WRLEN contains the number of bytes in the buffer (8 to 


65535). Note that SCBLK:WRLEN is the actual number of bytes ` 


to be processed by the SYSCALL, not the allocated size of the 
buffer. These parameters are used in SYSCALLs involving 


filenames to specify the (device and) filename desired, or as: 
, Gata buffer definitions for SYSCALL:WRITEB (Write Binary), T 
^. SCBLK: RDBUF and SCBLK:RDLEN select a buffer address and size 


“in which a SYSCALL result is returned. The SCBLK:RDLEN must 
: contain the expected maximum size of the result (in bytes).. 


SCBLK:RDLEN is the actual length of the reply given, that is, 
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the actual number of reply bytes placed in the RDBUF. If 


. RDBUF overlaps any part of the.SYSCALL block or ne WREUES, 
the SYSCALL. operation is not well defined. i 


. Bytes in the. SYSCALL block beyond SCBLK:RDLEN are ‘ate rosaus 
. in a manner specific. to the particular SYSCALL opcode (like . 


the SCBLK: PARAMS bytes). Most SYSCALLs do not need or use 


‘these hyres; 


An error occurring during execution of a C SYSCALL is handled 
in the manner described under: SDOS Error handling. The 


l calling sequence for SYSCALLS is EES 


LDX ` #SYSCALLBLOCKADDRESS 


JSR > -SYSCALL$ o^  (EQUATED TO $FB) ` : 
^ BCS OOPS We (Go PROCESS ERROR CODE IN x 
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- ERROR HANDLING 


~ Error Kanal ine is an duper tan’. art of any programming 
bo ‘System, It allows application programs to continue or effect 
o, recovery in spite of problems encountered: 


Errors detected by SDOS are. passed back | to phe der program ` 
. for inspection or handling. Sues es RS 


A Each error which can occur is assigned a 16 bit error code (Ø 
to 65535). Blocks of codes are assigned to each possible 

^ detector of an error (i.e., errors which SDOS detects have ^ 
codes. from 1000..to.1999,: compiled BASIC programs detect `. 
„errors 2 to.99, EDIT.errors are 200 to 299, etc.). — 


“Bach (assembly or SYSCALL) subroutine has two exits: a 

— success exit. (meaning no. unexpected/unrecoverable errors `` 
^ó6cürréed) and an error exit (meaning some error which the 
subroutine cannot handle occurred). 


If the success exit is taken, normal processing can continue. 
If the error exit is taken, an error code is passed back to 
the caller for his inspection. The caller has three options: 


v^. .-« 1.) Process and recover from the error empres fo r "No Such 
: ` File" error on an OPEN, a standard default file name might be 
OPENed). 


2.) Give up; notify the operator of the error and exit. 
3.) Decide to pass the error back to his did with an error 
indication. 


f Processing the error requires SEN checking for each of 
the possible error codes of interest (due to the large number 
of unexpected errors, an "if it's not this, it must be that" 
scheme is not very safe). Sometimes, data associated with 
the error is needed for the processing routine to continue; 

in these cases, the original detector of the error must have 
saved that data in a place agreed upon by the detector and 
the routine attempting recovery. An example is a "recovery" 

routine that prints out the Lógical Sector Number of a disk. 
sector on which a read error occurred -- the recovery routine 
*- Must know that a GETLASTBADLSN STATUS syscall will retrieve 
“the LSN destren, l | | 


“Giving up". i aidea by the SDOS SYSCALL: ERROREXIT. The 

“error code is "stored into the SYSCALL block, and the SYSCALL 
“is executed. :SDOS will print a text message corresponding. to 
the error codes and pass control to the command Interpro er: 
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- (DEFAULTPROGRAM). The command interpreter can. retrieve this 
error code, and a DO file can process it via IFERROR: 


‘Statements (see command interpreter description). 


~ Passing back: the. error code to. the next level of subroutine 


Carry reset on exit means the subroutine completed |. 
Successfully. The carry set on exit from a subroutine means 
"error occurred" (only for those subroutines which adhere to 
. this convention!); the X register contains a 16 bit error 
Code, Note that the calling subroutine must provide a BCS `. 

- after the JSR in order to detect an error. The ERROROCCURRED. .. 
routine tests the X register for errors from which it can 


is generally done only if the recovery routine does not- find 


an error code it is willing to handle. This provides an: 


: opportunity. for Subroutines at successively Bigher levels to 
“effect recovery... E 


- The subroutine' calling convention that implements this error 


———handling- prilesophy. is as CIL d 


(8) = 
yu BCS .. ERROROCCURRED ` A d 
+ _ SUCCESS EXIT © (S) = K HERE 
CLC GC | FLAG "SUCCESS EXIT" 
RTS m LE 
ERROROCCURRED EQU * (S) = K HERE 
CPX RERR:-- 
BEQ . HANDLEISTERROR 
CPX . #ERR:-- 
BEQ . =e 
RTS —— WITH CARRY STILL SET 
HANDLElSTERROR EQU * TO RECOVER FROM 1ST 
| ERROR 
Cho. o rat . . (OKRTS IN DEFS) 


RTS 


y s 
bo 
i 


recover; if the wrong error happens, no test will match and 
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; -. another RTS (with carry still set) will occur, providing the 


ences NOE higher level.subroutine a chance at processing the error 
Uo 070v code. In either case, error or not, the contents of the 
"^ Stack above the return address is untouched. The stack 


.". register itself has the original value of. the stack pointer. 
at tbe time of the JSR, so that all higher level routines can 
. be returned to exactly as normal. Last, notice that the 
^v HANDLEERROR and the success paths both exit by clearing the 
= carry (indicating "success" exit). Ge? e SE jc 


“2 SYSCALLS are implemented as subroutine calls and follow the ` 
above convention with one variation. If an error occurs, . 
8 unwinds the stack until a return address.on top of the ` 
k points to a BCC or BCS. This means that a SYSCALL must 
followed by a BCC/BCS or SDOS will unwind the stack too 
far; with unpredictable results. The. unwinding process ` l 
o consists. of repe: diy popping two bytes, and assuming Che 
Ee a OP OE the-s ack- is- return address , (with obviousl y bad ` 
= -Consequences if this is not true) until an appropriate return 
address is found (This scheme was chosen to minimize the 
amount of processing an SDOS routine had to do when it didn't 
care about errors, and has the side effect of speeding things 
up 5 to 10 percent). 
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""The error: "messages: Tisted here are for SbOS. Vi. D, 1. 1, BASIC 


E V1.3 and EDIT V1.1. 


- Program cónpleted normally. 


A sem 


v1.3 error messages: a 


Operator requested Attention 


Value Stack Overflow (expression too onp laxa 


For-Next Stack Overflow (too many active FOR-NEXT Loops) Me 
NEXT without FOR |... A TN PME 
^Gosub Stack “Overflow ` 


WRETURN-without-GOSUB - 

Conversion- Error- Pos 

- Input Buffer. Overflow 

- Array or Vector Subscript out E range 


l---.String.Subscript-out of range. 
^-"Sübstring length too long 
- Undefined Line Number encountered 
- Arithmetic Overflow Z 
- Non-Integer operand to Logical operator (& ! XOR COM **) 
=- Concatenated String exceeds CATMAX l 
- Tab count > 255 : E f Pas 
- Invalid FORMAT string ` us m f f Se 


I can't store that value into a byte 


= Illegal Argument to SIN/COS/TAN/ATN 
- Logarithm of B or negative number x 
- Square root attempted on negative number- 
- PEEK or POKE address < Ø or > 65535, or not an integer 
- POKE value <. or > 255, or not an integer 
= Attempt to POKE runtime package ` ou 
- Channel number > 255 m 
- File position < B or >= 2°31 ` 


System/Command Interpreter errors: 


1909 

101 
102 
103 


- Compilation or Assembly had fatal errors 

- Warning errors issued by Compiler or. Assembler 
- Bad Command Format 

- Can't do GOTO from CONSOLE: 
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--EDIToOr errors: 
BD .- Syntax Error & l 
“201 - Can't find branch target 
a. 282 = Can't find "J]J" 
 . 283 - Can't find matching "[" 
; - *** EDITOr error *** 
- Illegal argument. for command 
<= Zero is not a valid argument 
- Command requires argument 
— Command doesn't want an SE 
— No such "E" command l 
=~ Illegal character | 
| t hat as delimiter character. 


y ç 

3. - Too many Is" 
oom" must-be followed by printing character 
7 Command failed , 
—--Can't find string - ue 

~. Q register index must be 1 to 9 

- Need to open input file first 

- Text Buffer is full l 
220 - Command buffer is full 


; É | .,221 = Don't have enough lines in buffer to. J that far 
an . 222 - Illegal tab stop list ` 
š ` 223 ~ Need to select output file first 


E: | 224  - Unbalanced [ ]s 
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2,1880 

. 1801 
|. 1602 `: 

 - 18804. 
“1005 
..1096 


- No. such file 


“Length of file name > 16 characters | 
- New file already exists Ne 
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- SE checksum failed 
End of File encountered 


Can't DISMOUNT because a file is OPEN ` 


- Bad File Position Requested . | 
Number of Bytes per Cluster is. too big. (> 65535) 


No DISKMAP.SYS file, can't allocate or free. disk Brace 


No matching File Control. Block found 


No DEFAULTPROGRAM on default disk 
File is Delete protected 
File is Write protected 


uster Number out of range ` 


Disk- -Space exhausted - ee 
I tried to free an unallocated cluster Së 


- No more free FCBS (** *SYSTEM**X). 


File system is incompatible. with current file system (Vis 
File is being eE EEG f f 
Disk is mounted, can't change Map Algorithm 

Renamed-to filename isn't legal 

No ERRORMSGS.SYS file on drive B (think about this!) 

File name doesn't start with A thru Z or $ f En iy 
Illegal file Size specification 

Header cluster not initialized for RDCN eteh (***SyYSTEM**Í, 
Not enough (CNFG:)DSKBUFFERPOOL in I/O package . 

Disk Driver doesn't implement power fail 


Can't load that, not load format file 


MIKBUG record checksum failure 
Channel number is too big 


Channel is already open 


Channel is closed 

Illegal SYSCALL number 

Illegal Device operation requested 
Can't rename to a different device 


.SDOS load. record format error 
. Program too big to load 


Illegal LSN passed to physical disk qr iyo bs 


' CONSOLE: driver is sick 
Input buffer overflow in driver 


*** Program killed *** 


Device timed out 


Sector size is not a power of 2! (I/O: package fault) 
*** pot used *** f ER 2r S 
Disk read error 
Disk write error 
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Disk seek error ` 


Disk is write protected 


Disk device is software write locked. 


- SDOS self test checksum error! 


Number of LSN's >= 2°24, I quit! (1/0. package here 


Cluster size is too. small to SUpport, a file that big. 


SYSCALL block is too short 

SYSCALL Read-back buffer is too short for reply. 
SYSCALL Write data buffer is too short Mp en 

No such device in this configuration Ss 

Device errored f 


Device. must be a disk 
- Channel” D 
- Device no 
| TIME not set 


Dot open to the CONSOLES ca: Mur s 
ady | 
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SYSCALLS = Implementation 


This section details the. SYSCALLS implemented in: this Vereen: 


of. SDOS.. 


- Table pee sostas implemented in SDOS 1.0 


* uu OPCODE DEFINITIONS ' 
* ^. Eus 
ORG e f : p. 
= SYSCALL:OPEN - RMB 1 . OPEN FILE T E 
»SYSCALL:CREATE RMB H CREATE A NEW FILE ^ ^". ^ U 
ven SYSCALL:CLOSE. RMB. "Le. CLOSE A: PILE? ed ue. 
SYSCALL:RENAME RMB ` 1 ^A RENAME A FILE | S 
- SYSCALL:DELETE RMB . 1. ` DELETE A FILE ` 
SYSCALL:LOAD RMB. 1 LOAD AN OVERLAY 
SYSCALL:CHAIN ` RMB. 1 CHAIN TO A FILE 
-8YSCALL:CREATELOG -> RMB > © 1: - CREATE THE LOG FILE 
- SYSCALL:CLOSELOG RMB MOREM CLOSE THE LOG FILE 
 '"SYSCALL:DISKDEFAULT RMB l: SELECT DEFAULT DISK 
` DEVICE 


SYSCALL:READA RMB 1 READ ASCII BYTES FROM A FILE 
1 READ BINARY BYTES FROM A FILE 

SYSCALL:WRITEA  RMB EK WRITE ASCII BYTES TO A FILE ` 

SYSCALL:WRITEB  RMB l ". WRITE BINARY BYTES TO A FILE 

SYSCALL: CONTROL RMB 1 PERFORM A CONTROL OPERATION 

f ON À FILE/DEVICE: 


SYSCALL:STATUS RMB 1 READ FILE/DEVICE. STATUS 


SYSCALL:WAITDONE - RMB 1 WAIT FOR I/O ON 
f | ; - CHANNEL TO COMPLETE 
SYSCALL:EXIT RMB ` 1. GIVE CONTROL BACK TO THE | 
Set d | | - OPERATING SYSTEM 
.SYSCALL:ERROREXIT RMB 1 EXIT TO SYSTEM WITH 
i | | . ERROR CODE 
SYSCALL:SETERROR . ~~ RMB 1 REPORT AN ERROR TO 
| THE SYSTEM 
 SYSCALL: GETERROR UD s RMB ` 1 . READ BACK THE- LAST 
DE | ... ERROR CODE . E 
SYSCALL: DISPERROR RMB 1 DISPLAY ERROR MESSAGE 
| . ^ CORRESPONDING TO LAST 
| i ERROR CODE 
SYSCALL:KILLPROOF . RMB ot . . PREVENT USER PROGRAM 
Loos kg ne = T | FROM BEING KILLED | 
=: SYSCALL:KILLENABLE — RMB 1 ALLOW USER PROGRAM TO ` 
e EECH Se E E BE KILLED 
-—SYSCALL:DEBUG -RMB ' 1l CALL SYSTEM DEBUGGER |. 
- SYSCALL: ATTNCHECK RMB 1: OPERATOR ATTENTION 


REQUEST CHECK 
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RMB. 1 | CHECK FOR CHANNEL f 
| INPUT DEVICE - 
CONSOLE: d 
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SYSCALL:C OPEN 


< This SYSCALL is used to. establish an association EH an 
«existing file (to be read and/or updated) and an EI channel, 


| OPEN. SYSCALL Block Format: 


- SCBLK: OPCODE i EGE -. SYSCALL: OPEN 


SCBLK: WLEN ` SCH - SCBLK: END-SCBLK: OPCODE 
SCBLK: PARAMS FCB ` CHANNELNUMBER, IGNORED 
SCBLK: WRBUF © ` -FDB . FILENAMESTRING ` ` 
E f POINTS TO FIRST BYTE 
SCBLK:WRLEN | — FDB . FILENAMELENGTH 
je. uec actore EN BYTES S Qs 
— SCBLK: SRPLEN — RMB ^ AUS EXPECTED VALUE or. 2 

SCBLK: ROBUR < FDB SCANNEDCOUNT . 

I RE © # FILENAME CHARACTERS 
e E PROCESSED. ` 
SCBLK:RDLEN ^ PDP ` 2 SIZE OF RDBUF 
 SCBLK: END ,  EQU OE ; 


The WAIT flag must be zero. The first parameter byte is the 


channel number desired. The second parameter byte is not 


used. The Write Buffer (WRBUF) contains the filename 


¿(including device. name, etc.) desired, WRLEN- contains the 
number of bytes in the filename. 


The OPEN SYSCALL checks the channel to ensure that it. is aot 
open already. If not open, the filename is scanned to 


determine the selected device (default to DISK: if no device) 


and a filename on that device. The number of bytes scanned 
is returned as a 2 byte value in the buffer selected by ` 


RDBUF; the rest of the bytes in WRBUF are ignored... Leading 


blanks on the filename are ignored, but are included in the 


. scanned- count. (Note: All SYSCALLs that deal with file or. 


device names return the number of bytes of the filename 
Scanned as the result. The entire filename is scanned even 


"if an error occurs.) The device is searched for the file. if 
"it is a directoried device, and an error issued if not found. 
If the device is not a directoried device, the device is; 


simply opened (Note: output only đevices cannot be OPENed!). 


: The file is positioned so that a subsequent read will read ` 
_ the zeroth byte of the file. | 


"LU done) possible errors are: ` 


BAD FILE NAME `- 
NO SUCH FILE 
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CAN'T OPEN, MUST CREATE 
NO SUCH DEVICE 
CHANNEL BUSY 
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- SYSCALL:CREATE 


This SYSCALL is used to CREATE a new file and establish an ` 


association between an I/O channel number and the new file. |. Ge, 


"It is also used when a program will do output only to a 


device (such as a line printer; the philosophy. is that. such” 


output. is a new file). 


CREATE SYSCALL Block Format: 


SCBLK: OPCODE FOB  SYSCALL: CREATE 


SCBLK:WLEN. FCB SCBLK:END-SCBLK: OPCODE 

SCBLK: PARAMS FCB _CHANNELNO, IGNORED 

SCBLK:WRBUF FDB `: FILENAMESTRING 

SCBLK : WRLEN FDB ` F ILENAMELENGTH 

, SCBLK: RPLEN . RMB: 2 EXPECTED VALUE op 2 
SCBLK: RDBUF FDB SCANNEDCOUNT 

SCBLK:RDLEN FDB 2. i SIZE OF SCANNED COUNT 
SCBLK:END EQU PE 


The WAIT flag must be zero. The first EE byte i us 


desired channel number; the second parameter byte is ignored. 


WRBUF points to the filename (device name) of the new. file. 


Like SYSCALL: OPEN, RDBUF points to a 2 byte area in which the 
number of bytes of the filename scanned cx SDOS. is placed on 


completion of the SYSCALL. 


If a disk file is specified on. there is an ‘old file, the old 
file must not be delete or write protected or an error will 
occur and the new file will not be created (nor will the 
channel be opened). Otherwise, the new file is created, and 
“the channel is opened. If an old file: does exist; an OPEN. 


SYSCALL executed after the CREATE, looking for the same file; e 


will find the old file. If the system crashes before the new- 7 sow 


file is closed, the old file will be unaffected. in any van, 


Even after the new file is closed, channels still open to E. iaaa 


-= old file will not notice. any difference. . When the. Fast kote 
channel to the old file is closed, the space for the old file 


` is returned to free disk space. Effectively, a CREATE 
includes an "implied" delete of the older version of the 
file. I ' 


- The file is positioned so that a write will write ite first 
2 pyre in byte #0 of the: file. 


Possible errors are: 
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FILE IS DELETE PROTECTED 
FILE IS WRITE PROTECTED 
NO SUCH DEVICE 
CHANNEL IS BUSY . 

BAD FILENAME . | 
FILE IS BEING CREATE 
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 SYSCALL:CLOSE 


. The CLOSE SYSCALL is used to py aa the association between an 
ETA) channel number and a file. JF 


CLOSE SYSCALL Format: 


“SCBLK:OPCODE FCB ` SYSCALL:CLOSE 
SCBLK:WLEN . FCB SCBLK : END-SCBLK : OPCODE 
SCBLK:PARAMS. ` FCB  . CHANNELNO, IGNORED 
SCBLK:END ` EQU * | | 


APRIS ‘SYSCALL "frees the 13/0 channel to be QUERN. to another 
i i EES “and causes the CLOSE entry point of a device driver to ^ 
(wo be called. Action of the driver is driver-dependent.- 


LE the channel was open to a disk file, then changes to the 
file size, protection, and other characteristics are updated. 
on the disk (not before). If the disk file is newly created, 
‘and is not replacing another by the same name, closing will 
make its name appear in the directory. If the file is newly 
Ss created, and it is a replacement for a file that already 
SE l exists (i.e., one by the same name), then the new file will 

! replace the old in the directory, and the disk space 
allocated to the old file will be returned to free space as 
Soon as no other I/O channels remain open to the old version 
of the file. 


. Possible errors are: 


ILLEGAL CHANNEL NUMBER 
CHANNEL IS ALREADY CLOSED 
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SYSCALL: RENAME 


The RENAME Syscall is used to change the name of. a. file. The 
file must be open on some channel; it must not be a newly 


created file, and no file (new. or old) having the. new name 


must exist . 


RENAME SYSCALL Ee 


SCBLK:OPCODE . FCB: SYSCALL:RENAME 


."SCBLK:WLEN | FCB ` SCBLK:END-SCBLK:OPCODE 
` "SCBLK:PARAMS ` FCB ` CHANNELNUMBER, IGNORED Gs 
SCBLK:WRBUF FDB = NEWFILENAME | | 
SCBLK:WRLEN |. . FDB . | NEHFILENAMELENGTH ` s TNR" 
SCBLK: RPLEN RMB | 2 EXPECTED VALUE = 2 
SCBLK: RDBUF FDB ` SCANNEDCOUNT | | 
 SCBLK:RDLEN-. -FDB 2 A 
SCBLK:END ` EQU. * 


The SYSCALL format is identical to that of an OPEN syscall; 


parameters and results are passed the same vare 


This SYSCALL affects nothing except the name of the file. 


RENAMEing a disk file to its own name is legal, and can speed 


up later OPENs of that file since a rename causes the file 
name to be re-hashed into the ohh ec trys: Refer to ` 
hash-lookup EEN of files. 


Possible errors are: 


BAD FILE NAME 

FILE IS BEING CREATED 

CAN'T RENAME TO A DIFFERENT DEVICE 
FILE IS DELETE PROTECTED 

FILE IS WRITE PROTECTED 

NEW FILE EXIS ‘TS ALREADY ` 
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SYSCALL: DELETE ` 


^ The DELETE SYSCALL is used to delete . a file from a disk : 
device. I 


DELETE | SYSCALL Format: 


.SCBLK:OPCODE ` FCB  SYSCALL:DELETE 


-SCBLK:WLEN FCB `  SCBLK:END-SCBLK:OPCODE 
| SCBLK:PARAMS : FCB .. IGNORED, IGNORED - 
SCBLK:WRLEN .FDB .FILENAMEBUFFER ` 
i SCBLK: :WRBUF FDB  FILENAMESIZE 
~~ SCBEKrRPLEN ` ` RMB ` 2 EXPECTED: VALUE 
SCBLK:RDBUF ...... FDB . REPLYBUFFER - a` 
-SCBLK : RDLEN FDB .- REPLYBUFFERSIZE ` 
SCBLK: END f EQU * : 


———————————————— Mise ia 


phe file specified on the specified device is deleted ‘(this 


syscall is not legal for devices which do not have 
directories). No I/O channel is specified or needed. If the 
deletion is successful, the directory entry is removed: so | 
that the file can no longer be opened. If the file is open 
on some I/O channel when the deléte SYSCALL is issued, then 
the SYSCALL will complete successfully, but the file will not 


actually be deleted until the last channel open to the file 
.is closed (in fact, the file may actually be allocated more 
disk space via the other channel!). 


The reply buffer is loaded with the actual length of the 
filename (see SYSCALL:OPEN). 


Possible errors are: 


NO SUCH FILE 
FILE IS DELETE PROTECTED 
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SYSCADL LOAD 


ae «The LOAD Syscall is used to load an overlay program segment 


into memory ,. without transferring control. 


Sp LOAD SYSCALL Format: ` ` 


SCBLK: :OPCODE FCB ^ SYSCALL:LOAD 


SCBLK:WLEN .  FCB . SCBLK: END-SCBLE: OPCODE 
. SCBLK:PARAMS. . FCB —  IGNORED,IGNORED | 
` SCBLK:WRBUF . FDB FILENAMESTRING 
SCBLK:WRLEN. . . -FDB FILENAMELENGTH 
. SCBLK: RPLEN RMB 2 EXPECTED VALUE OF 4 
“SCBLK:RDBUF ^ ^ FDB = COUNTANDSTART 
SCBLK:RDLEN |. ^ FDB £4 - MINIMUM REQUIRED 
tr o PD d, er t s RUE IT 


No channel number need bg specified. 


The filename specified is opened on a ee system. Geer, 


and checked to see if a load format file is given (first byte 
must be ASCII "S" or Hex :01). If so, the file contents are ` 


loaded into memory as specified by the load records (see 
- LOADER FORMATS). Scatter loading (loading into 


non-contiguous parts of memory) is possible. Upon completion. 
of the loading process, control is returned to the user, and 
the file is closed. i l SZ ; 


The results returned in the reply buffer are 2 bytes of 


. filename count (the first 2 bytes; see SYSCALL:OPEN) and 2 
‘bytes of start address E second 2) as specified by the 


load records.. 


Load records which would load on top or above SDOS cause the 


load to be aborted. 


== A load record whose «address conflicts with that of the reply 
| buffer may be damaged; conversely, the reply may be garbled. 

Loading into the area used by the stack may cause SDOS to... 

blow up. SDOS does not check for this. 


| 
l 


Errors while loading cause the error exit of the Syscall to. 
cbe taken. 


“In any case, on: ‘completion of the 1684, the file is closed. 


. Possible errors are: 
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Us sS. 


NOT A LOAD FILE 
.NO SUCH FILE. 
EOF HIT 
2 CHECKSUM ERROR. fe gs 
culis ul 7. LOAD RECORD FORMAT ERROR. | 
q. a BAD FILENAME SIZE 
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(57 CHAIN SYSCALL Format: 


"SYSCALL: CHAIN 


The CHAIN syscall. is used to load and. transfer control to an 


SDOS USER'S MANUAL 


overlay or program segment. 


.SCBLK:OPCODE ` FCB SYSCALL:CHAIN 
. SCBLK:iWLEN `- ČS FCB — ^ SYSCALL:END-SYSCALL: ORCODE 
.SCBLK:PARAMS .. FCB . . IGNORED,IGNORED. . 


2. §CBLK:WRBUF. Pop .. FILENAMESTRING >= - 
-GSCBLKTWRLEN- === FDB- FILENAMELENGTH | 7770 70007 
SCBLKiRPLEN.———RMB : 2 >... EXPECTED VALUE: OF D 
c^. SCBLK:RDBUF. FDB |^ COUNTANDSTART mu 
ae SCBLK:RDLEN .  FDB 4. MINIMUM REQUIRED - Gen 
SE —M ur SCBLK: TET END” — P QU E x D * ` AP —— at 


CHAIN first closes all 1/0 Channels except channel: e. te Ñ 
then causes all modified disk sectors in the LRU queue to get 


written back to the disk to ensure validity of disk contents, | 


and then performs exactly the same function as SYSCALL: LOAD. 


except that the error exit will be taken only for the 


following errors:. 


BAD FILE NAME 

BAD FILE NAME SIZE. 
FILE NOT FOUND ` 

NOT A LOAD FILE. 


All other errors will cause an: Awol lea SYSCALL: ERROREXIT to 
be executed (because of the possibility of the. program 


issuing the CHAIN being overlayed). 


: On successful completion of the load, control will be 

transferred to the start address of the file. The sta 
"¿pointer is set to the contents of $FC,$FD, minus 1 (see "soos 
Memory Map). me l 
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C SYSCALL: EE, 


"nnéreé are occasions on which a record of termindd session 


would be very convenient, such as when a purported bug 


. arises, or as a pedagogical example. This copy can be 
-<< laboriously constructed by hand, or it can be mads. 
automatically via a SE syscall, l 


 CREATELOG SYSCALL Format: 


SCBLK:OPCODE FCB SYSCALL:CREATELOG ` 


- SCBLK:WLEN ^ FCB SCBLK:END-SCBLK:OPCODE 
SCBLK:PARAMS FCB . | CHANNELNO,IGNORED . 
SCBLK:WRBUF. ^. FDB ` FILENAMESTRING | S 
SCBLK#WRLEN FDB ^'^ FILENAMELENGTH. 

_ SCBLK:RPLEN -RMB 2 EXPECTED VALUE OF 2 

o  SCBLK:RDBUF: | . FDB... .SCANNEDCOUNT . _. A Y 

SCBLK:RDLEN -FDB . 2 . SIZE OF SCANNED COUNT 
SCBLK:END . „EQU * | 


CREATELOG creates a new file (just like the CREATE Send 
but no channel number is given (SDOS reserves a special, 
unnumbered, I/O channel specifically for this purpose). It 
returns file name size information in the same manner as 


OPEN. 


There is no way for a user program to explicitly read or 
write data to the log channel; all I/O through the log 
channel is done invisibly by SDOS. Essentially, any data 


"written via a Write ASCII to channel Ø (the control channel) 


is also. copied to the log file. Data read via a Read ASCII 
on channel Ø is also written to the log file. In this way, a 
complete copy of console sessions (carried on through the 
control channel) is recorded in the log file for later 
retrieval. The writes to the log file are done anly KEN the 
log file is open (has been created). 


STATUS and CONTROL syscalls are re-directed from channel B to 
the log channel when it is open, so that status information 
read from channel OG may not actually be that of channel Ø. 


ALL other channel-oriented syscalls (in particular, Read ` 
¿Binary and Write Binary) are not affected by the log channel. 
If the log channel.is not open, it has no effect whatsoever 


on. channel H operations... 


The. log file will not be found in the directory until it is 


closed (via CLOSELOG). Like any CREATEd disk file, PROGRAM 
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KILL (^C^C) automatically closes the log file. This Syscall. 
.is used mainly by SDOSCOMMANDS to implement the LOG and Di 
commands. l 

A program can set up a po file by: 


i. ) ‘Verifying that the DO file exists apy Coe it on some 


 Hehannei. 


2.) CLOSEing channel ra 


| 3.) OPENing channel Ø to the DO Pile 
- 4.) CREATELOG on the "CONSOLE:" device . 


ÀN 


- ^ Further input will come from the DO file. If an error occurs 
"during step 2 or 3, the program must reOPEN channel L. to the ev TE 
CONSOLE: Orono | further- Console 1/90 can occur. " JH SEN 


e Possible. errors. are: M PE ! p - Gy Wig < : 5 < EE PEE A no E RN m 


CHANNEL Ne OPEN 
ILLEGAL FILE NAME 
NO DISK SPACE 
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SYSCALL: CLOSELOG 


This Syscall is used to close the special dog GE channel 
(see SYSCALL: CREATELOG) . 


CLOSELOG SYSCALL Format: 


SCBLK:OPCODE ` FCB ^ ` SYSCALL:CLOSELOG st 
SCBLK:WLEN — FCB. — SCBLK:END-SCBLK: OPCODE. 
SCBLK:END EQU 


This Syscall EE the .same GE as a CLOSE Syscall - 
on the Log channe1. . No channel number or other. parameters 


are needed. 


< Possible d rola are: ` 


. CHANNEL-NOT-OPEN ` 


Copyright (C) 1978 Software Dynamics 
-118- 


SDOS USER'S MANUAL 


SYSCALL:DISKDEPAULT 


ds 


This SYSCALL is used to select which disk is default- -selected 
when:a file name with no explicit disk device indentification 
is given. | SE 


 DISKDEFAULT SYSCALL Format: 


"SCBLK: OPCODE. E FOB ` SYSCALL:DISKDEFAULT 


SCBLK:WLEN = FCB ^ SCBLK:END-SCBLK: OPCODE 
` SCBLK:PARAMS ` FCB IGNORED, IGNORED. 
SCBLK: | WRBUF ` o- FDB ` ` FILENAMESTRING Lt 
s E - + POINTS TO FIRST BYTE ` ` 
SS Ee f SCBLK: WRLEN FDB FILENAMELENGTH 
"Jae e RI ses Maree n D i S . à i ` n I N BYTE S ES * CS? 
T Nx >- SCBLK:RPLEN - RMB ^ 2 ` EXPECTED VALUE OF 2 
OS SCBLK:RDBUF — FDB . . SCANNEDCOUNT. Tm 
DM NM d A e! # FILENAME CHARS. PROCESSED. 
. SCBLK: RDLEN. FDB ` 2 SIZE OF RDBUF 
SCBLK: END |^ EQUS * | 


j DISKDEFAULT parses the device name, and ensures that the 
device name is a valid disk device name (filenames passed 
with the device name are not examined). The specified disk 


| a will then be used whenever a filename with no device 
A specification is encountered by a filename SYSCALL. 
| No channel number is needed. | | 
Data is returned in the same form as an OPEN syscall. 
After a successful return, the device name DISK: refers to 
the default disk. : l 
Possible errors are? 
DEVICE IS NOT A DISK 
GR 
| 
CH 
ç 
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“this SYSCALL is used to read (ASCII) textual data from a 


8 file. The file must be oper on some 1/9 channel. 


| READA SYSCALL Block 


SCBLK: OPCODE 
_ SCBLK:WLEN 


SCBLK: PARAMS 


"SCBLK:WRBUF ` 


SCBLK:RPLEN "rum 


Ln... CBS pes 


SCBLK: RDLEN 


SCBLK:END 


"U"SCBLK: HRRLEN 


Format: 
FCB 
| FCB 
FCB 
-FDB 


RMB 


FDB- 


FDB 


EQU. 


RMB 2 


SYSCALL:READA 
SCBLK:END-SCBLK:OPCODE 
CHANNELNUMBER , LMFLAG 


H 


(MINIMIZES PROCESSING, TIME) 


2 

ACTUAL: NUMBER BYTES READ I 
READBUFFER ius 
WHERE TO PUT DATA 
READBUFSIZE 


J MAXIMUM NUMBER BYTES TO READ 
* 


READA will read the specified number of bytes into the read 
buffer from the file open on the specified channel, and 
advance the file position past the number of bytes examined, 
Subject to the following conditions: the file has enough 
bytes, and no other errors occur during the read.  Nulls 

£A), and rubouts (:7F) are deleted from. 
the stream of characters read from the file/device. I 


(:80), line feeds (: 


Bit 7 of all characters read via SYSCALL: READA is zeroed. 
Other characters may be removed from the input stream by the 


particular device driver in use. 


The column count for this channel. is updated for each byte 
placed in the read-back buffer, according to the following 
rule: a printing character 


to be incremented. 


CR (:0D) 


(:20-:7E) causes the column count 
causes the column count to be 


zeroed. All other codes leave the count alone. The column f 
count can be read by a SYSCALL: STATUS call. - 


If LMFLAG is non-zero, the read proceeds in single line iodé: 


If a CR (:0D) character is encountered, it will be placed in 
“the read buffer, and the read will be terminated. Cee ni^ 
Pi Venta CRs from (enn the read. : 


- SCBLK: RPLEN is set to the actual number of bytes read, even 


. if an error occurs. 
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lo 
Dod 


—— 


- The WRBUF is ignored if supplied. 


All data read from channel Ø via a READA. is copied (via f 
ee DE B 3 -WRITEA) to the log file if the log channel has been opened. 
COITO A READA with LMFLAG-1 directed at channel f will be completed 
205 from the CONSOLE: device if a complete line cannot be read 
. ^ because of an EOF error: (this finishes a partial line from a 
“we DO file). 2 ` posed I : M i ; x 


: RITEA, SYSCALL:WRITEB, and SYSCALL:READB. 
: An EOF hit error will occur: (1) if not in line mode and the 
butter cannot be filled; (2) if in line mode and no CR 


character is encountered before EOF. E 

An end-of-file condition (which can be sensed via a k 
SYSCALL:STATUS) is set whenever a read of the last data byte 

| of the file occurs. 


Possible errors are: 


rr 


CHANNEL NOT OPEN 
EOF HIT 
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SYSCALL:READB 


"This SYSCALL is used to read binary data from a file. The 
file must be open on some I/O channel. S dn l 


me READE Syscall Block format : | 


SCBLK:OPCODE ` FCB SYSCALL: READB 


^ SCBLK:WLEN — ` FCB SCBLK:END-SCBLK:OPCODE 
“SCBLK:PARAMS FCB CHANNELNUMBER, IGNORED | 
^ SCBLK:WRBUF~- © RMB . 2 aa oo 


..SCBLK:WRLEN FDB = B . |. et S 
Sie wa 40767. MINIMIZES PROCESSING TIME) 
"MARTE A | ACTUAL NUMBER BYTES READ ` 


(2 >, SCBLK:RDBUP .. .FDB- READBUFFER. ` | 
pM Ww WHERE TO PUT DATA 
COUUCUUTTOSCBLK:RDLEN 777^ FDB ^ ^ READBUFSIZE ` : 


| ` | MAXIMUM NUMBER BYTES TO READ 
 SCBLK:END EQU * 


READB will read the specified number of bytes into the read 
buffer from the file opened on the specified I/O channel, and 
advance the file position by the number of bytes actually 
read. In order for the specified buffer to be completely 
filled, the distance between the current file position and 

. the end of the file must be greater or equal to the buffer 
Size, and no errors may occur during the read. The data 
bytes read from the file are not changed in any way. 


. SCBLK:RPLEN is set to the actual number of data bytes read 
(usually equal to the buffer size). 


Using a READB SYSCALL causes the column count for the 
Specified channel to be zeroed. : ee 


SCBLK:WRBUF is ignored if supplied; however, its length 
should be specified as zero to minimize SYSCALL processing 


n. ime... 


An EOF error will occur if the read request is not completely 


"satisfied (i.e., the buffer was not filled)., 


"The overhead for doing single-byte reads is high; long 


_., buffers will distribute this overhead so that the average 
"Line per byte is some 40 times faster than single byte reads. 


Possible errors are: 
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ME. | ..^' CHANNEL NOT OPEN 
| Pop HIT. | 

DISK READ ERROR ' 

DEVICE NOT READY 

DEVICE TIMED OUT 
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SYSCALL:WRITEA 
 WRITEA is used to Write ASCII data to a file. The primary: 
difference between this and WRITEB is that the column count 
gets updated, and certain output editing is done. 

= WRITEA SYSCALL Format: | 


SCBLK: OPCODE FOB ` SYSCALL:WRITEA 


-SCBLK:WLEN ^ FCB SCBLK:END-SCBLK: OPCODE | 

. SCBLK:PARAMS FCB CHANNELNUMBER, IGNORED 

. SCBLK:WRBUF | FDB  WRITEDATABUFFER | og | 
SCBLK: :WRLEN -FDB ` NUMBEROFBYTESTOWRITE | uu s s. 


"The. data bytes in “the WRITEDATABUFFER | are ‘copied to ‘the file 
“open on the specified I/O channel. The file position is 


"e c PUR “advanced by NUMBEROFBYTESTOWRITE. Disk files are extended ` 


automatically, if necessary, to make more room and the file 

Size is changed. The column count for this I/O channel is 

changed according to the same rules as specified by 

SYSCALL:READA. The output stream may be modified by the 

device driver; a CRT driver will typically add LF (:@A) and 
"nulls (idle characters) after a CR. (: ØD) character. 


SDOS conventions dictate that LF characters are superflous in 
the presence of CR characters. To write a line of text to a 
file (or device), terminating it with a CR is sufficient. 
An EOF condition will happen if the last data byte of the 
file is overwritten, and/or the file was extended in order to 
accomodate the write request... An EOF condition on a WRITE to 
à disk does not cause an error. l . 
Data written via WRITEAS to channel Ø is also sent (via 
WRITEAS) to the log channel if the log channel is open. 
Multi-byte writes are more efficient than single- byte writes. | 
No read- ~back buffer is required. | 
Possible errors are: 

CHANNEL NOT. OPEN 

DISK SPACE EXHAUSTED (for disk files) 

DISK WRITE ERROR 

“DEVICE TIMED OUT 

DEVICE NOT READY 
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. SYSCALL:WRITEB 


The WRITEB SYSCALL is used to write binary data to a file. ` 
- The stream of data bytes is copied directly to the file or - 
device without any change to its content. To 


` WRITEB SYSCALL Format: . 


SCBLK:OPCODE FCB — SYSCALL:WRITEB 


SCBLK:WLEN . | -FCB  SCBLK:END-SCBLK:OPCODE ` 
SCBLK:PARAMS.. FCB CHANNELNUMBER,IGNORED : 
| SCBLK:WRBUF , epp WRITEDATABUFFER 2. 060. ee usse 
 SCBLK:WRLEN ` ^ FDB ` NUMBEROFBYTESTOWRITE © ^ 0 
decem x I ce cad Ee 


The data bytes in the specified buffer are copied without ©... 
Change to the file that is open on the specified I/O channel. 


The file position is advanced by NUMBEROFBYTESTOWRITE. If 
necessary, a disk file is extended automatically to make more 


room, and the file size is adjusted accordingly. The column 
count for this channel is zeroed. ^ ^g | . 


Multi-byte writes are more efficient than single-byte writes. 


- An EOF condition will happen if the last data byte of the 
file is overwritten, and/or the file was extended in order to 
. accomodate the write request. o : 


No réad-back buffer is required. 
Possible errors are: 


CHANNEL NOT OPEN 

DISK SPACE EXHAUSTED . ; 

ILLEGAL DEVICE OPERATION 
(for line-printer-like devices) 

DISK WRITE ERROR : l 

DEVICE NOT READY 
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: SYSCALL: CONTROL 


This SYSCALL is used to control or modify the operation of a 


. device/file. The first parameter byte selects the I/O 


channel number; the second parameter byte determines the. 


..actual operation performed (rewind, eject, ‘dismount, etc.) so 


this SYSCALL actually represents an entire class of ee 

Operations. A control operation may be issued only to an 1/0 ` 

channel that jis already OPEN. | NW ui 

If logging is active, and a CONTROL operation is issued for | 

channel ð, the control operation is actually applied to the 
.ieg channel, LU o o ns ss 

<= CONTROL SYSCALL Block Format: 

SCBLK:OPCODE |. FCB . . SYSCALL:CONTROL 


.SCBLK:WLEN FCB. SCBLK:END-SCBLK:OPCODE 
SCBLK: PARAMS FCB CHANNELNUMBER ` 

f FCB ` .CC:controlcode 
SCBLK:WRBUF FDB CONTROLPARAMETERS 
SCBLK : WRLEN FDB NUMBEROFCONTROLBYTES 
SCBLK: END EQU BRS 


SDOS divides device control operations into two classes: 
common, and device specific. Common control operations are 
those operations for which all devices generally have a 
capability. Currently only the following operations fit in 


the category of common: 
CC:POSITION and CC:DUMPBUFFERS 


All other control operations are device specific and are 
. documented with the specific device driver. Typical 
device-specific operations include: select echo mode, set 
tabs, and dismount disk. | 


The format of the CONTROL SYSCALLS varies because different 

device operations require different parameters. In i 
particular, most CONTROL SYSCALLs do not require a write 

-. buffer. For. specific formats, refer to the device driver 

.. descriptions. e? | 
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CC:POSITION 


CC: POSITION is used to select the next. byte of a file to be 
read/written. A 4 byte, 2's complement integer is used to 


E select the byte index into a (disk) file (it can also. be used | 


as a record number, a port number, a screen position,: or 
whatever is. appropriate for the device). The number must be 
positive (i.e., the sign bit must be zero), » Following a > 
CC:POSITION command, further read/writes start from the 


specified file position and advance sequentially. A "rewind". ` 


is obtained by Spee tty ing a zero for the valne: of the 4 byte 


integer. 


“Setting. a file position SE equal or greater tha d s! 


size.of the (disk) file will- cause. an EOF condition: to occur 
and cause an error. . 


| No reply is given. ` 


Alphanümeric CRTs are an interesting special case. It is 


. Standard for SDOS CRT drivers to interpret the positioning 
parameter as cursor positioning data. The parameter is. 


interpreted as 2 bytes of garbage, 1 byte to specify the 
Screen row number (zero being the top screen row) and 1 byte 


^ of column number (zero being the leftmost column). Given R 


for row and C for column, the value of the positioning 


-parameter is then R*2564C. In this way, cursor positioning 


on screens is generalized to work for a broad variety of CRT 
displays. 


CC: POSITION SYSCALL Format: 


` SCBLK:OPCODE FCB.. SYSCALL: CONTROL 


SCBLK:WLEN FCB - SCBLK:RPLEN-SCBLK: OPCODE 
SCBLK: PARAMS : FCB CHANNELNUMBER, CC: POSITION 
- SCBLK:WRBUF FDB POSITIONDATA 
E SCBLK:WRLEN FDB . > 4. 
i. POSITIONDATA RMB 4. NEED FILE POSITION 
i | SE 
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For CRTs, POSITIONDATA has the following form: 


POSITIONDATA FCB 


| 9,0 - 
ee SCREENROW RMB ` 1 
ec wv |: . SCREENCOL RMB i: 
CC: DUMPBUFFERS d | EE SE 


ee: DUMPBUFFERS is- eed to force an 1/0. device to "dump any vu 
buffers it may still have filled. Ho parameters: are cC 
"required; operation is device specific. 


CC:DUMPBUFFERS Format: 


SCBLK:OPCODE ` FCB .SYSCALL: CONTROL 


SCBLK:WLEN FCB SCBLK :WRBUF-SCBLK : OPCODE 
SCBLK: PARAMS FCB CHANNELNUMBER,CC: DUMPBUFFERS 
T 
| 
MU ' 
$ 
| 
T3 
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| SYSCALL:STATUS ` 


"The STATUS Syscall is used to read file or device-dependent 
.descriptive data about that file or device (as opposed to | ` 


reading data from the file or device itself). This syscall 
.. is really an entire group of operations; a parameter byte . 


selects the device-specific data to read. A STATUS Syscall 
must. reference an open I/O channel. Like READA and READB, . 
the data is read back into the reply buffer. 


< If a STATUS syscall is issued for channel Ü, and logging is 
active, the status read back, will be that of the log channel, 
not. Channel. Üy IRAE : SE O D 
.. STATUS SYSCALL Block Format: . 


SCBLK:OPCODE FCB SYSCALL:STATUS 


CUvUUUTOCTSCBLKIWLEN FCB (C  SYSCALL:END-SYSCALL:OPCODE 
o: SCBLK:PARAMS ` FCB CHANNELNO,SC:statuscode 
SCBLK:WRBUF ` FDB - IGNORED 
SCBLK:WRLEN FDB . IGNORED 
, SCBLK:RPLEN FDB CHANGED ! 
/ SCBLK:RDBUF FDB STATUSBUFFER 


SCBLK:RDLEN ` . FDB STATUSCODEDEPENDENTLENGTH 


There are two classes of STATUS requests: those standard 
across all devices, and those specific to the particular 
‘device type. The following status information is obtainable 
from most devices: 


SC:GETPOS 
SC:GETCOL 
SC:GETEOF 
SC:GETFILESIZE 
SC:GETTYP 
SC:GETPARAMS 


All other status-reading operations are device specific and 
‘are detailed under the specific device drivers. 


-SCiGETPOS is used to read the current position in a file, 


—i.e., if one executes a CC:POSITION command, an SC:GETPOS 


will read back the same value as the positioning value given 
for the CC:POSITION. SC:GETPOS always reads back four data 
. bytes (the interpretation of these bytes is up to the device 
. driver). dan RS Z^ Sechs. sd Ee 


" SC:GETCOL reads back the print position of a simulated print 
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| 
1 
l: 
j 


- head on a particular I/O çhannel (see READA, WRITEA 
°° syscalls). Ø means "no characters printed on this line." 
en one data byte is Feturnegs 


SC: GETEOF returns a. eee flag. E whether the 
. I/O channel has positioned, ‘read or written past the last 

data byte in the file. A non-zero returned. byte indicates. 
. past or. at end of file; zero means more data can be read from . 

. the file before the end of file is encountered., 


. 8C: GETFILESIZE retains the size of the file (in bytes). The 


Size is returned às a^ “four byte integer, appropriate for use. 
in-a ‘positioning command (this is convenient ‘for appending 


="data to the end of a file). ` This is normally only l 
implemented on disk files. - 


CUTUSCTGETTYP returns a Single-byte device type: “code, which 


places a device into one of the following classes: FILE, 


DISK, TAPE, DIRECTORIED TAPE, CONSOLE, LINEPRINTER, 


SERIALOUT, SERIALIN, PARALELLOUT, PARALELLIN, DUMMY. Other 
device types may be added as needed. 


SC:GETPARAMS reads device class-specific parameters. To know 
what kind of data to expect for a reply, the program must f 
^ first determine the device type (using SC:GETTYP). Currently 


defined  device-specific parameters are: 


f Disk FILE: 


DVDAT:NSPC NUMBER OF SECTORS PER CLUSTER 
DVDAT:NBPS SECTOR SIZE IN BYTES 


.The maximum file size may be computed as: 


| (NBPS*NSPC/2-1) *NBPS*NSPC 


DISK Device: 


DVDAT:NBPS NUMBER OF BYTES PER SECTOR. 


 DVDAT:NSPT ` NUMBER OF SECTORS PER TRACK 
DVDAT: NTPC NUMBER OF TRACKS PER CYLINDER 
Pane DVDAT:NCYL = NUMBER OF CYLINDERS | 
NL = | 
vemm BVDAT: WIDTH IN CHARACTERS ` `. 


^ DVDAT: DEPTH IF SCREEN ORIENTED; 
d IF CONTINUOUS FORM PAPER 


Copyright (C) 1978 Software Dynamics 
l -122- 
| f 


270,7 BDOS: USER'S MANUAL. >» 


. PRINTER: ^. 77 "k s VT aues 
| © DVDAT:WIDTH . . IN CHARACTERS ` 


l 


N, 
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. SYSCALL:WAITDONE 


This system call is used to wait for. an operation initiated 
on an I/O channel to complete. : ' 


This SYSCALL and the ‘parallel initiation feature ARE NOT 

. IMPLEMENTED IN FINAL FORM. It currently.is a no-operation, | 
~- and is provided to allow programs to be coded as though Ra 

"parallel SYSCALLS were: implemented. ` 


WAITDONE SYSCALL Format: 


SCBLK:OPCODE .. FCB ` SYSCADL:WAITDONE io 00 
-SCBLK:WLEN © > FCB ` ` SCBLK:END-SCBLK: 2 
.SCBLK:PARAMS .. PCB + CHANNELNUMBER - x. 
SCBLK:END DE C 


Lf any parallel. “SYSCALL (a syscall With: the WAIT flag = 
"don't wait") was issued on the specified I/O channel, 


WAITDONE delays the execution of the user program until that 


Operation is complete. Error status returned is that of the 


parallel SYSCALL returned as though the parallel. SYSCALL. had l 
the WAIT flag reset when executed. 


A second WAITDONE issued on an I/O channel, without any other 
intervening SYSCALLS, returns immediately with no error 


^. possible, so multiple WAITDONEs on a channel may be performed 


without conflicts arising. 
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b RUR y 


This syscall is used by a user program to. pass control o the 
. DEFAULTPROGRAM. It is an indication that the user program 
completed execution successfully. i 


EXIT SYSCALL Format: 


SCBLK:OPCODE ` FCB | SYSCALL: EXIT 


SCBLK:WLEN ^ ` FOB ` SCBLK: END- -SCBLK: : OPCODE . 
. SCBLK: END, ` d vu ZS Ds 


tee are no- parameters, and control does not return to the 
. user program, E vx I E 


All 1/0 channels except. channel: e are oer, 


^ "$DOS does a “quick checksum’ on itself after an EXIT dB e 
"completed, and reports an error if it thinks memory is 
starting to fail; otherwise, no errors are possible. 


This syscall is functionally identical to SYSCALL: ERROREXIT 
with an error code of 0. Pec 
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SYSCALL:ERROREXIT x 


This Syscall is used by a user program to. cease execution, 
abnormally, and notify the MOM the reason for Stopping. 


. BRROREXIT SYSCALL Format: 


 SCBLK:OPCODE . FCB ^ SYSCALL:ERROREXIT 


:  SCBLK:WLEN. | . FCB SCBLK:END-SCBLK: OPCODE 
. , SCBLK:PARAMS FDB "ERBORCODE 
SCBLK: END ` - EQU 


E e The error code ` is” ‘displayed on othe console as: c. TE 


: Error nnnnn «CR» ` 
Oort: 
i «TEXT MESSAGE» .(nnnnn) «CR? 


depending on whether SDOS' can successfully extract the 

corresponding text message from the ERRORMSGS.SYS file on 

drive ð` (see SYSCALL: DISPERROR). If the error code is 9, a 

message is displayed. Control is then passed to the 

DEFAULTPROGRAM (usually the SDOS command interpreter, which 

can interrogate and conditionally branch on the error code if 
dit. a DO file is being processed). No error is possible. 


This syscall is intended to Bà used as very simple error 
handling in user programs. i 
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.QoPS . 


oo IGIVEUP ` 


ERROREXIT 


“SDOS USER'S MANUAL ` 


OLDX oc #PARAMETERLISTADDRESS 


JSR. . SYSCALLS 
BCS. OOPS B/ ERROR 
-CPX ^ ZERR: o. | 
BEQ ICANHANDLEIT1 
CPX #ERR:... 

BEQ . ICANHANDLEIT2 


STX | -ERROREXIT+SCBLK:PARAMS | 


LDX = #ERROREXIT 

JSR SYSCALLS 

BCS CAN'T GET HERE! 
JMP * 

FCB SYSCALL: ERROREXIT 

FCB 4. SCBLK:WLEN - 


FDB H 


- Copyright (C) 
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| SYSCALL: SETERROR 


This syscall, coupled with SYSCALL: .DISPERROR, . is. used 2 a 
Program ‘to Q the reason a SYSCALL failed. ` 


-SETERROR SYSCALL Format: 


SCBLK:OPCODE COEUR . SYSCALL:SETERROR © 


SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE 
S a . SCBLK:PARAMS | FDB ^  ERRORCODE 
SCBLK: END — EQU "e Se 


The user program first stores an error code. into the syscall 
^ "block, and then issues the syscall. The error code has now 
been stored in SDOS. for use by the DISPERROR and GETERROR 

Co vov syscalls. Normally, a SETERROR is followed by a DISPERROR, 

c .89.that.a text display. of the error cause occurs. Since 

- ^ . control returns to the user program, this is an effective 
"procedure for displaying the cause of an error without ` 
"^ EXITing to the DEFAULTPROGRAM. 


A GETERROR syscall can be used to later retrieve the error 
code. A subsequent EXIT or ERROREXIT syscall will change the 
SC oo. code set by SETERROR. ` . 
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| SYSCALL: GETERROR 


SCBLK:OPCODE ` ` 
, SCBLK:iWLEN  ... 
SCBLK: PARAMS ` 
SCBLK:WRBUF 
` SCBLK:WRLEN. 
“"""""SCBLK:RPLEN ' 
|. SCBLK: 'RDBUF. 


` SCBLK:RDLEN.. 


SCBLK: END 


` GETERROR SYSCALL Format: 


FCB 
_ FCB. 
FDB. 


FDB 


hos FDB 


-FDB 


FDB ` 
FDB. 


EQU 


_ This syscall is used to retrieve an error code. given to SDOS | 
= by EXIT, ERROREXIT, or SETERROR syscalls, E? 


SYSCALL:GETERROR f 
SYSCALL:END- SCBLK: OPCODE 
IGNORED 
IGNORED 
IGNORED zr 
A EXPECTED "VALUE ` 
'ERRORCODEBUF 
WHERE. TO PUT ERROR. CODE 
D, UN ‘LENGTH. OF 16 BIT 


ERROR CODE: 
* 


The 2 byte error code last given to SDOS is "rekurnéd in the 


dBBELIDIDE are necessary. 


- Possible errors are: 


U reply buffer. -No parameters other than the reply buffer 


SYSCALL LENGTH TOO SHORT 
READ-BACK BUFFER TOO SHORT 


D 
SCH 
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- SYSCALL:DISPERROR 
0 The DISPERROR is used to display a text message corresponding 
(0000007 to the most recent error code given to SDOS by SYSCALL:EXIT, 
:  SYSCALL:ERROREXIT, or SYSCALL:SETERROR. == ^. 
|. DISPERROR SYSCALL Block Format: | 
00 7 SOBEK:OPCODE | FCB ` SYSCALL:DISPERROR 
ai Š SCBLK:END Sonn : 


<TEXT FROM ERRORMSGS.SYS» (nnnnn) . «CR» 


is displayed on channel 0. If channel Ø is not open, SDOS ` 
: automatically opens it to the CONSOLE: device.  SDOS gets the 
ert message from the ERRORMSGS.SYS file based on the error 
2 . code. If SDOS cannot retrieve the error message from the ` 
i .. ERRORMSGS.SYS file, it displays the simpler. form, with nnnnn 
being the decimal equivalent of the error code. Nò carriage 
return is output, so that the user program may precede or 
append text to the error message (such as ... AT LINE 100 
for BASIC). I piety Po | l 


l i l | I 

- "If an error occurs during the process of displaying the 
message, SDOS will hang. The operator must re-boot. This 
can only occur if SDOS cannot output to the CONSOLE:. 
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SYSCALL:KILLPROOF ` ` 


x .. This SYSCALL is used by an application which needs to perform 
CU777777 a long process of computation or I/O without being killed by 
a the operator for correct operation. This situation occurs 

“When several files need to be updated in order to maintain 
data base consistency. .  . 6 id l 


. KILLPROOF SYSCALL Block Format: ` d 
""SGBLR:OPCÓDE ` ` sp — SYSCALL: KILLPROOF 


. -SCBLK:WLEN ` FCB ` . SCBLK: END-SCBLK: OPCODE E: 
CLCLUSCBLKIEND. UU (Wl Re ea IL EE 


EQU eis 


Z= ÑNormally, when: the operator types ^C^C, SDOS kills the n 
currently running program and causes a forced ERROREXIT. 

^ This in turn.displays an appropriate message and causes the 
- DEFAULTPROGRAM to be loaded (actually, the 1/0 package 
detects the ^C^C and calls an SDOS subroutine, B 
SDOS:KILLPROGRAM). 


A double ^C (operator abort) (a call to SDOS:KILLPROGRAM by 
f f the I/O package) is ignored by KILLPROGRAM if: a KILLPROOF 
géie  . syscall has been executed more recently that a KILLENABLE 
^ syscall. Operation of.the program continues undisturbed. 
| The user program can still sense operator. attention requests 
via the ATTNCHECK syscall. i f 


If. the operator requests program kill when the program is 
KILLPROOF, the kill request is saved. . When. the program 

` Switches from KILLPROOF to KILLENABLEd, it will be killed 
instantly. ` f 


On EXIT, SDOS switches user programs back to KILLENABLEd mode 
automatically, (actually, the DEFAULTPROGRAM is loaded as a 
. KILLENABLEd user program) so a set of programs invoked by a 
DO file is killable.  SYSCALL:CHAIN does not affect the 
KILLENABLE status of a program, so a large program consisting 
"of several serially executed segments can operate entirely  - 
(|. .;KILLPROOFed if needed. `` ger Ps 


"Possible errors are: ^ 


. . SYSCALL BLOCK TOO SHORT 
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,SYSCALL: KILLENABLE 


. This syscall allows a program to. be killed b ‘the operator. 
| It is normally. only used after a critical portion of a 
. program, running KILLDISABLEd, is finished executing.: 


KILLENABLE SYSCALL Block Format: ` 


| SCBLK:OPCODE o FOB  SYSCALL:KILLENABLE 
SCBLK:iWLEN 00 FCB SCBLK: END-SCBLK:OPCODE ` 
SCBLK:END EQU 


= Executing. this. Syscall. will allow. a program to. Be: killed. when id 
“the operator types. "CG (when the I/O package calls. - : 
SDOS:KILLPROGRAM)... If a ^C^C (call to SDOS:KILLPROGRAM) has 


occurred while the user program was KILLPROOF, execution of 
the KILLENABLE syscall will cause the program to quit 
execution immediately (i. e. control does not return to: the 
user program in this case). ; 


SDOSCOMMANDS (the command interpreter) runs KILLENABLEd and 


loads user programs initially KILLENABLEd. The user program 


must execute a KILLDISABLE syscall before performing any 


critical operations (see KILLDISABLE syscall). CHAIN 
SyScalls do not affect the KILLENABLE status of the user. 
program. 


PROGRAM KILLED 
SYSCALL ‘BLOCK TOO SHORT 
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x SYSCALL:DEBUG 


The DEBUG syscall - is “used to transfer control from a user. 


-program to the local system debugger. 


^- DEBUG SYSCALL Block Format: ` 


SCBLK:OPCODE .. FCB SYSCALL: DEBUG 


SCBLK:WLEN ` ` FCB SCBLK:END-SCBLK:OPCODE | 
-SCBLK:END .. EE en EE 


No " parameters are needed. Control is passed to the System 
<- debugger ' s entry point. The actual method of passing control . ... | 
is 1/0 package dependent. If: there. is. no A -an A EE. 
BRROREXIT is forced. ee ee Ge a 


For systems. with: -IDB,. control is: EE to the debugger in oe 


- Such a way that a non-maskable interrupt appears to have 


occurred. EXIT from IDB should be made via a "G" command. 


Using nnnnG to exit IDB and return to the user Program will. 


also work. 


If a "G" command is executed) control returns to the user 
program just beyond the call, as with any other SYSCALL. 


Possible errors are: 


SYSCALL TOO SHORT 
NO DEBUGGER 
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SDOS USER'S MANUAL ` ` 


This SYSCALL is used to determine if the operator would like : 


.to interact with the user program (the operator normally `. 
. signals this by striking the ESCape key on his console; the. 


actual mechanism is determined by the I/O package). 
ATTNCHECK SYSCALL Block Format: 


J SCBLK:iOPCODE ` Fc | .— SYSCALL:ATTNCHECK - 


SCBLK:WLEN —-:-FCB SCBLK: END-SCBLK: FOPCODE ` 
SCBLK:END ` EQU ` 


UT he: ATTNCHECK syscall will return normally it: no attention. 


has been requested | since the last ATTNCHECK syscall. If the. 


operator has requested attention at least once since the last o - 


ATTNCHECK SYSCALL was issued, then. an error. exit is. taken: 
with error code ERR:ATTENTION.  '- I D 


There are no parameters and no returned results. 


Note that depressing ESCape terminates line input mode from 
the CONSOLE:; thus, with suitable program design, ESCape can 
be used to get a program out of one interaction mode and into 
another mode of interaction. ; 


Copyright (C) 1978 Software Dynamics 
| -134- 
i | . 


SYSCALL: ISCONSOLE 


SDOS USER'S MANUAL 


This. system call is used to determine if channel zero is open ` 


to the operator's console (this is needed because a STATUS 


syscall will read back the status of the. log channel if 
logging is active). 


This SYSCALL is used primarily by the Gonna M 
(when an error is encountered) to determine Ke or not a 
DO file should be aborted. 


 1SCONSOLE SYSCALL Block Format: 


- SCBLK:OPCODE ^ ` FCB. ^ SYSCALL:1SCONSOLE 


SCBLK:WLEN ^ ^ FCB ` SCBLK:END-SCBLK:OPCODE | 
"SCBLK:END ese EQUS os E49. "n IM SD 


There are no parameters and no returned results. A normal "` 
exit indicates that channel zero truly is open to the console 
device; otherwise, an error exit occurs. - The only possible ` 
errors are: 


CHANNEL IS NOT OPEN AT ALL ` 
CHANNEL H IS OPEN; BUT NOT TO THE CONSOLE 
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SAMPLE PROGRAM USING SYSCALLS 
This. is a sample assembly longues program to list a file to 
the CONSOLE: (i.e., it does exactly the same thing as a LIST 
. file command does), and illustrates the use of SYSCALLs and 
Nr recovery. l i . 


MAL/6800 1.2: 0100 


21/19/79 14:02:45; Page 2; Form 1 ` LIST PROGRAM. IN ASSEMBLY 
EN om ae ORG $100 NICE PLACE FOR A SMALL PROGRAM 
qid 2c FIRST, “EQUATE THE CONSTANTS WE WILL BE USING | 
33: * IN THE PROGRAM 
35; CHANNELO EQU g CHANNEL THE USER IS ON 
| 36: CHANNEL: EQU 1 CHANNEL FOR FILE 1/0 
37: LINEMODE EQU J. INPUT IN LINE MODE 
OKT | | 
39; * . l f ; ` l i 
40: * TO START OFF, PRINT OUT A PROMPTING MESSAGE TO 
41: * THE USER (WHO IS ON CHANNEL 8) 
; E uet. eur. BBD ee Se 
SS 0100 CE0150 43: START  LDX ` #HIMESSAGE 
0103 BDØØFB 44: JSR SYSCALLS - 
S B 45: * IF WE GET AN ERROR ON PRINTING THE HI MESSAGE. 
46: * (I.E., THE CARRY IS SET), THIS BCS WILL TAKE 
47: * US TO THE ERROR ROUTINE WHICH WILL IN TURN DO 
^us 48: * AN ERROR EXIT 
9106 252C 49: BCS ERROR 
: 50: * 
51: * NOW INPUT THE NAME OF THE FILE THE USER WISHES 
52: *- TO LIST TO HIS/HER TERMINAL 
53: * 
£108 CE@17B 54: | LDX #INPUTFILENAME 
Diop BDØØFB 55: JSR SYSCALL$ 
VIVE 2524 56: BCS ERROR 
k jer e Sy es d | 
58: * 
59: * NEXT, OPEN THE FILE...TO DO THIS WE SET THE LENGTH 
60: * OF THE FILE, NAME IN THE OPEN SYSCALL BLOCK EQUAL T 
6l: * THE # OF CHARACTERS READ IN IN THE LAST SYSCALL. 
| 62: * WE DON'T HAVE TO MOVE THE FILE NAME ANYWHERE SINCE 
63: * WE VERY CLEVERLY MADE THE PLACE THAT SDOS WILL LOO 
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Eege 


s A 


024116 CEO18B 


0119 BDØØFB ` 
011C 2516 ` 


CN pns 

L 
011E CE0195 
.0121 BDOOFB 
0124 2517 

^ 


Em MAL /6880. 1.2: 
01/19/79 14:02:45; 


1110 FE0183 ` 


PF01911 


8110... 


DX DE AA 


+ * A * sg 


READLOOP- 


EE * * 


KR 


_SDOS USER'S MANUAL | ee a 


Page E Form poe LIST PROGRAM IN ASSEMBLY ` 


| a 


AT. FOR THE: FILE NAME THE SAME: PLACE WHERE Sbos 


READ IN THE STRING FROM THE. USER. (SIMILAR TO: — 


INPUT AS 
OPEN #1,A$ 
Q 


“GET HOW MANY CHARS THE USER TYPED IN 
© LDX. — INPUTFILENAME+READA: ACTUALCOUNT 


“SET THE LENGTH OF FILE NAME TO + CHARS READ IN. 
OS TX OPENFILE+OPEN: LENGTE ` 
| LDX #OPENFILE -ADDRESS OF SYSCALL BLOCK 
JSR SYSCALLS  . HAVE SDOS OPEN UP. THE FILE 


BCS ERROR IF CARRY IS SET, WE GOT AN ERROR 


START THE MAIN LOOP OF THE PROGRAM... 


 ». FIRST READ IN A LINE FROM THE INPUT FILE 


LDX ` -#READALINE ` ` SYSCALL BLOCK 


JSR. SYSCALLS HAVE SDOS READ US IN A LINI 


NOW CHECK TO SEE IF THE READ GOT AN ERROR. 


IF IT DID, SEE IF THE ERROR WAS AN END OF FILE. 


BCS CHECKFOREOF 


IF WE GET TO HERE, WE KNOW WE DIDN'T GET AN ERROR. 


SO SET THE LENGTH OF THE. WRITE BUFFER - 
I HOW,MANY CHARS WE READ IN. 
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MAL/6800 1.2: 6129 
81/19/13 14: £2: 45; Page 4; Form 1 LIST PROGRAM IN ASSEMBLY 
0126 FEO19D ~ 98: LDX READALINE+READA: : ACTUALCOUNT 
. 0129 FFÜlAB 99; ` SN ` WRITEALINE+WRITEA: :COUNT 
ee, 100: * > : l 
101: * AND SEND THE LINE our TO THE USER 
eL MG 102: * e 
CED1A5 103: . . | . LDX ` #WRITEALINE 
- BDØØFB 104: |. | JSR SYSCALLS | 
24EA . 105: BE READLOOP ^ | IF WE DIDN'T GET AN ERRO 
"^ «uv 8 I. € osos UT 2 de READ NEXT LINE 
Se 107: * 
169: * “ERROR ROUTINE: COPY ERROR CODE IN X TO À SYSCALL 
..118:.*. BLOCK WHICH WILL HAVE SDOS PRINT OUT THE 
DP ws 2111: * Se ERROR MESSAGE AND EXIT 
yl cL x PUE 112: * PN. | 
* | 0134 FFÜlAF 113: ERROR `. STX ` "ERROREXIT4ERROREXIT: CODE 
8137 CE@1AD 114: LDX. . #ERROREXIT 
£13A 7EØØFB 115: "JMP SYSCALL$ ` : DON'T. NEED A JSR 
ll6: * SINCE SDOS WON'T COME BAC 
: 117: * 
j I 118: * e ! 
SAN, t 1 E. 119: *- CHECK FOR EOF: IF EOF, WRAP THINGS UP AND EXIT 
TaN 120: * OTHERWISE, DO AN ERROR EXIT C 
l : 121: * 
813D 8C03E9 122: CHECKFOREOF CPX | #ERR:EOFHIT EOF ERROR? 
0140 26F2 123: BNE ERROR IF NOT, GIVE THE USER THE ERROR 
124: * f 
| 125: * PRINT OUT "I'M DONE" TYPE MESSAGE 
. Gë SI 126: * EM U 
0142 CE01B1 127: “` LDX #BYEMESSAGE 
0145 BDØØFB 128: JSR SYSCALLS 
(@148 25EA (129: - BCS _ ERROR MURPHY! S LAW STRIKES AGAIN! 
130: * : 
.131: * ' NOW DO AN EXIT. WE. DO A JMP INSTEAD OF A 
i a. | ^ 132: * JSR SINCE SDOS WILL NOT RETURN TO US 
m O po WM E Stee Mee RON 
914A CE@1D7 134:  . LDX HEXIT TE 
. .814D 7E09FB 135: .- - JMP SYSCALLS ——  . ee 3 
DP tuc EE E uit | x SR vae 
E EKOS END OF CODE 
, 138: * E 
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Ge OCA 
E .MAL/6808 1.2: 0158 ; _ i 
Mais R 14: 82: 45; Page 5; Form 1 XA  [SYSCALL BLOCKS 
| 141: * ` BLOCKS FOR SYSCALLS ` ` 
142: * ^ - | | 
143: ` | | 
144; * | THE HI MESSAGE WHICH WE PRINT OUT TO THE USER 
' 145: 
. 146: 'BIMESSAGE . FCB SYSCALL:WRITEA . 
02147: FCB  WRITEA:SCLEN 
ey ae A PCR ` CHANNELS ) Se 
149; ETC 1 “FILLER TO GET TO THE BUFFER. POINTER 
me Lëps, --FDB. | HITEXT POINTER ‘TO ACTUAL MESSAGE e 
Sbr BS a HITEXTLEN.. ..- LENGTH OF MESSAGE. 
152: ` e I S ve e ne 
| 153: HITEXT FCC © ‘HI! WHAT FILE DO YOU WANT TO LIST? ' 
(154: HITEXTLEN ^ EQU... -*-HITEXT ` - "HOW BIG IS THE MSG? 
RES ge EE Suites FOI E as | 
156: PE D aie OE 
157: * .SYSCALL BLOCK FOR INPUTING TEXT FROM USER 
P 158: | | 
017B ØA 159: INPUTFILENAME FCB SYSCALL:READA 
. . Ü817C BE. . 168: FCB READA:SCLEN 
¿y -017D 08. 161: .. FCB ' CHANNEL - FROM THE USER 
(o ^ 817E BI- 162: FCB LINEMODE WE WANT TO INPUT UPTO A CR 
i "| 017F 0006 163; ; RMB 6 SKIP PAST WRITE BUFFERS 
0185 Ging . 164: ` FDB | | FILENAMEBUF READ BUFFER 
0187 £100 ` 165: 2 FDB FILENAMEBUFMAX MAX AMOUNT TO READ 
0189 0002 166: . | RMB |. 2 ACTUAL COUNT. (SET ON RETURN) 
" 167: l. - 
168: * |. SYSCALL BLOCK FOR OPEN FILE 
GE 169: SNE ER | ME 
018B 08 178: OPENFILE FCB SYSCALL: OPEN 
018C BE 171: — . ` ` PCB - OPEN:SCLEN ` | 
018D Øl 172: | i FCB CHANNEL] 


®18E 0001 173: © , RMB 1 FILLER 
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MAL/6800 1.2: | 
01/19/79 14:02:45; beads 6; Form 1 


G18F 


` 0191 


6195 


8196 


£197. 


8198 
0199 
g19F 
g1Al 


 £1A3 


@1A5 
B1A6 
91A7 
01A8 
01A9 
ÜlAB 


ÜlAD 
ÜlAE 
Q.lAF 


91B1 
g1B2 


g1B3 


61B4 


HIER 


0004 
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8191 


174: 
175: 
176: 
177: 
178: 
179: 
180: ` 


"LOLs 


182: 
183; 


185: 


186: 


187: 


|: 188: 
| 189; 


196: 


. 191: 
192: 


193: 
194; 
195: 
196: 
197: 
198: 
199; 
208: 
201: 
202: 
203: 
204: 


. 205: 


206: 


up: 


SYSCALL BLOCKS s 
FDB ^ FILENAMEBUF WHERE USER'S INPUT IS 
. RMB 4 BUFFER LENGTH (SET BY PROGRAM). 
*  . SYSCALL BLOCK FOR READING IN A LINE FROM THE FILE 
READALINE FCB SYSCALL:READA. 
FCB. READA:SCLEN = 
FCB  CHANNEL1 
` FCB . LINEMODE 
` RMB. 6°.: SKIP PAST WRITE BUFFERS 
.FDB. READBUFFER ` | | 
" FDB. — READBUFFERMAX | i 
RB . 2, COUNT OF HOW MUCH WAS READ IN 
* ` SYSCALL BLOCK FOR PRINTING LINE ON USER TERMINAL 
WRITEALINE , FCB SYSCALL:WRITEA 
FCB WRITEA:SCLEN ` ` 
- FCB CHANNEL > 
RMB] FILLER ` 
FDB. ^ WRITEBUFFER Meee 
RMB 2 LENGTH OF LINE | e 
. ERROR EXIT . | 
. ERROREXIT FCB SYSCALL:ERROREXIT 
FCB ERROREXIT:SCLEN 
RMB 2 THIS WILL CONTAIN THE ERROR CODE 
* . GOOD BYE MESSAGE 
BYEMESSAGE ` FCB SYSCALL:WRITEA 
| FCB WRITEA:SCLEN 
FCB CHANNELÓ | 
RMB 1 
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MAL/6800 1.2: 01B7 


81/19/79 14: 
01B5 Ø1B9 ' 


0187 ØØ1E 


01B9 2A2A2A 
£1D6 8D 


001E 


01D7 11 
ging 02 


.81D9 
g1D9 
£1D9 
0100 
0100 

01D9 p100 


02:45; Page 7; Form 1: : 


208: ` -FDB 


228: RMB 

229; * 

238: * “THAT'S: A 
231: * : 
232: | END 


ER'S MANUAL 


` SYSCALL BLOCKS 


" BYETEXT 


2289; ` FDB BYETEXTLEN 

210: 0° E I I GE a zi 
211: BYETEXT FCC "**** THAT'S ALL FOR NOW ****x" 
. 212: |». FCB “SOD CARRIAGE RETURN 
213: BYETEXTLEN - EQU . *-BYETEXT 0 

214 | RM 

215: * | ^ ^. NORMAL EXIT 

216: "2. à pes P 

217: EXIT. FCB. SYSCALL:EXIT "^. 

21812 5 7 TOB ^ SSEXITISCLEN: C ` d 

2 1 9: - x. PELO S ` p SAS Z S Ue 

220 V menie ge 

221: * _` AND HERE'S. THE 1/0. BUFFER 

222: | 1 : 

223% FILENAMEBUF EQU "a 

224: READBUFFER EQU . 

225: WRITEBUFFER EQU | * 

226: FILENAMEBUFMAX  EQU - $100 

227: READBUFFERMAX EQU — $180 


READBUFFERMAX SPACE FOR BUFFER 


LL FOLKS! 


Copyright (C). 1978 Software Dynamics 
i -141- 


SDOS USER'S MANUAL 


WRITING and DEBUGGING User Assembly Programs. 


Writing. a User Assembly-Language program to run under spos ` 
requires the following steps: l 


1.) Use EDIT (or some other means) to place the desired 
assembly source program on a disk. 


2s ) Use ASM to produce a listing. (optional) and a um 
..  (MIKbug) version: of the desired program: p 


^ 3a. ) Execute the program by typing its name 
j `. or 


pue b. ) Debug the. program by typing 


.DEBUG name ` 


C mi. will pass control to the local system: debugger (usually. 
IDB). and debugging may commence... 


Note: Breakpoints should not be placed on a BCC/BCS after a 
SYSCALL (SDOS will not see the BCx if an error occurs and a 
System failure will result). Further, breakpoints should all 
_ be removed before a SYSCALL:EXIT or SYSCALL:ERROREXIT is ` 
executed. Also, SDOS has no "warm start" entry point; if the 
program runs away, the operator's only safe choice is to 
re-boot. 


4.) When the program works satisfactorily, MAKEBINARY should 
be used to reduce the load time. 
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MEMORY MAP 
The memory of the 6880 computer, when SE a user 


“program under SDOS, has the following e 


Ñ ` LOCATIONS d aoe CONTENTS 


Scratch temporaries, usable by user program. ` 
Note: These temporaries are also used by SDOS; 
so any SYSCALL will destroy their contents. 
| $O8-SEF ` DO e S SCH CH n se x 
oe? Vu / User program page zero. Not used by SDOS or 
‘the I/OÓ package. ` : E 
GO SPOSSEA. er ye 2 SOY 4 SC fee E SC 
— D . System dependent data used by system hardware 
- (ROM), I/O package or interrupt routines for 
any purpose; see specific I/O packages. User 
programs must not disturb this data; 


references to this data will make the program 
hardware or configuration dependent. 
$FB,SFC,SFD | 
- SYSCALL entry point. . These three bytes 
contain a JMP to the SYSCALL entry point in- 
SDOS. All user programs should define 

. SYSCALL$ as $FB; this will make them ` 
independent of the actual location of SDOS. ` 
These bytes are initialized by SDOS whenever a 
CHAIN or LOAD SYSCALL is executed. Bytes 
SFC,$FD form a 16 bit pointer to the first 
byte of SDOS (to the first byte above the 
memory space available to the user.program). 


SFE,SFF. . A 
; Reserved for system dependent data (typically 
a pointer to last byte or page of. RAMI User 
prógram must not Ge or use. 
$100-(SDOS-1) |. ^. SR Tes 
: ; User program area. Used in any way desired by 
user programs. Last byte of this area has an 
_ address equal to contents of (SFC, $FD) minus 
“1, On entry (CHAIN) to a user program, the 
stack register is set to this value (SDOS-1). 
Generally, user programs have a start address 
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E 
of $108. 
SDOS -- x | X as 
| Beginning of SDOS aa I/Q package). User ` 
" program may not overlay or store any byte on 
or above this pauni: 
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. Typical SDOS Address Space 


c LOW 5 d 5 ees 
| "PAGE ZERO 


-SD SOFTWARE or 
| CUSTOMER SOFTWARE! 


| 


vt 
TTY, ! I f 
LINEPRINTER, i I/O PACKAGE 
DRIVERS, i 
- S(ETC.) .l. ^ ^ DISK READ 
; . : i 1 
! 
1 
1 
l 
! 
! 
l 
! 
I 


| DISK WAITDONE 


DISK 
SECTOR 
BUFFERS 


| 32K 

TO ` : 

56K DEPENDING ON 
CONFIGURATION 


SDOS 
(DISK FILE 
^ MANAGEMENT) 


` gen ges Se gen Gom doe gem do gen dem que Ge Pu due Pu fen bom (um Ome Ven pun Gem Pen qoo gu due ooe ten Gow s s 


1 
TIME ` TE EE l 
| otc Ce š 6 7 Z NON-EXISTENT MEMORY 


SE LM IDB 
uc 


gem qm dun om gie s s 


.ROM VECTORS TO OTHER ROM 
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EE will load files containing one of two: types. of. records: 


Ic ) SDOS Load Records ` 


"ML )- MIKBUG: Records”: 


..A file to be loaded must contain ‘only SDOS load records, or: 
SE MIKBUG Records,- but. never a mixture." 


[..8DbOS. LOAD . RECORD FORMATS. 


o SDOS. Load Records are: designed to. let. SDOS load large blocks. 
a of. contiguous memory efficiently, and still retain 


Scatter-load capability. A file containing SDOS Load ecole 


"appears as a stream of load records. Each load record has a 
hype. and. format. There are four-SDOS- load record: types; >r: 
all four. contain: binary- information for ease of processing by 


the loader -and to minimize file space occupied. Each load 
record type is identified by its first byte. One record 
immediately follows another. 


SDOS load record type 1 must be the first record (i.e., start 


on byte 0) of the file. It is followed by 2 bytes forming a 


16 bit start address, MSB first. The next two bytes are the 
l6 bit one's complement of the start address, MSB first (this 
record format makes it extremely improbable that a non-load 
format file is actually loaded by accident). : l 


SDOS load record type Ø is a skip record.. The twò bytes. 


following the record type byte form a 16 bit count (MSB 


first) ọf the number of bytes following the skip record to 
ignore. The loader processes this record by positioning the 


file to the file position after the Skip record, plus count 


bytes. This record format is used to align following load 
records on power of two boundaries which can pecos: up loading 
of larger data records. 


 SDOS load record’ types 2: and 3 are identical in format. Both 
. ¿record types are used to load blocks of data into the memory 
” address specified by the two bytes following the record type 
_._yte (MSB first), The number of bytes to be loaded is given... 


by the 16 bit count specified by the next two bytes (MSB 


first). | The data bytes to be loaded SE follow the 
= Count bytes. x E 


SECH type 2 record specifies that another load ‘record follows. 


(i. e., that EOF does not immediately FOLLOW. the records: and 
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that further load record processing is needed. A type 3 
record indicates that the load process is complete once the - 
data bytes in the type 3 record are loaded (i.e., there are ` 
no more load records in the file). After processing a type 3 . 
. record, a SYSCALL:CHAIN will transfer control to the start | 
"address specified by the type 1 record. f 
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 SDOS LOAD RECORD FORMATS 


~~. Command 


Wenn em 
el 


COUNT BYTES. 
ad Skip COUNT ene to find 
.next command. UsSed.as.a .. 
Space filler to pad to the 


Ge next physical sector boundary. 
p gar ADDRESS 1 16 BIT CHECKSUM T . Set start address. 
iust 6d 1 ! Must be first command 
2 BYTES `. : | STE ` in file. CHECKSUM is. 
:FFFF ~ address. 
1 2 ADDRESS ` ! SE 1 DATA BYTES IR 
H ! ! 1 ! Me ete ! 
2 BYTES 2 BYTES ctia 1 
E 
$ f 
COUNT BYTES 
Causes data bytes to be aer 
sequentially into memory 
= Starting with the specified 
address. 
D 3 ! ADDRESS l COUNT - 1. DATA BYTES ! 
er ! ! ! ! ! : ! 
2 2 BYTES 2 BYTES 


Just like 2, but aleo causes 
JUMP to start -address specified, 


The utility program, MAKEBINARY, converts MIKBUG format load 


files into SDOS load record format. lies, and does some 
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S ta alignment of data records on power-of- two positions within 

o— oc: Ehe load file. This optimization is intended to increase the. 
SE . probability that large load records, with addresses that are 

. a multiple of the physical sector size for a disk, start on a 

"physical sector boundary within a file, thus providing SDOS. 

` with the opportunity to do direct. DMA reads from the disk 

file. 


ey 


EES aa eska EAD ir a voc 
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aye e E DL fe. 


The load records are used in the following way to optimize ` ` 
. the disk reads. (example): .. q E ws UOI e cq 


= = >= Z Z = Zx Z = < — == < Zm amar ve ama esse aswa 
Se Sm Ss SS SKS mss estes 


- Must be first in file! 


-Logical byte #'s 4 Type l record | 
lL ! Type ð record ! -Filler record 
2 E . MË 
d 47 ! f ; x 
esch JL Type 2 record |! Indicates "Load next 
EN ` y Sp I=================i two sectors" ^ SA = 
NBPS.:  . 1 IST Data Byte |! 
= e e EE 
E E E Ñ a : | 1 =======s========== 
I E E I 
` 2 l ! 
I we I=================1 P. š . ; 
3*NBPS 1 Type 3 record ! Indicates "Load next 
L ! two sectors" and 
1 ! transfer control to 
f de Y ! start address when 
! ! done. . 
ZN : f I==========z=s=s====i : 
: 4*NBPS ` ! ! 
Sg f ! ! 
[=================i 


MIKBUG LOAD RECORD FORMATS 


MIKBUG records are handled by SDOS to retain compatibility 

with Motorola compatible software. MIKBUG records are 

inefficient on both space and load time because all binary 

data which participates in the load process is stored in: 

ASCII format, 2 hex digits per byte, and requires conversion 
. by the loader. 8 l : i 1 - 


| Only two MIKBUG record types are processed by SDOS: Sl and S9 
records. SE peu. ; 


H 
t 
I 
1 


Sl records specify a count byte, a load address (2 bytes) and 
er a set of data bytes to be loaded into sequentially increasing 
— .. 7777 38üresses starting with the load address, and a checksum 
U : byte. Each "byte" is represented by 2 ASCII hexadecimal 

“digits (6-9,A-F). The count byte includes the address and 
the checksum byte. The address has its MSB first, LSB 


pe 
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I i second. The. checksum byte is equal in value to hex Ep minus 
— he sum of the binary values of the count, address MSB and 
Ge | LSB, and all the data eae modulo 230 


e ` Example: S1061002A7D967 _ f 


< "$9 records are used to mark end of a load file. Officially, 

=— iO records also contain a start address; SDOS ignores this 
and uses the first load E given. By an SI Terora as TERE 
` ¿Start address. ` : 


OR {hex : 8D) characters. and nulls are legal between MIKBUG 
“load records, but nowhere else. . No other characters are 
legal in a MIKBUG image load file. 


.The SD .6808 Assembler Produces "binary" load files in MIKBUG 
coccformat. Bn duds NS 
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SDOS DISK FILE STRUCTURE | 
z This section: gives detailed information on the Becuctare of 
` the SDOS disk file system. Two concepts are critical to the. 
understanding of the file system: Logical Sector Numbers and 
Logical Cluster Numbers. These- Concepts are detailed below. 
Definitions: RET | oe 
NBPS ^. Number of bytes/sector (2°n,n=1..15). Must be power 
"of 21! NBPS is limited to 128*32-4896 by eo TREC OY 
search routine. Minimum size is 128 Bytes 
RN .*- (see BOOT sector). Ve Ue 3 
- NSPT . Number of: ‘gectors/track 
NTPC | Number of tracks/cylinder. f 
' CWCYL Number of cylinders/drive snas 5 
———sNumber- of-(logical) sectors on a disk dere 
RE | NSPT*NTPC*NCYL) f I 
Note: Number of bytes/cluster « 25 16 for 6808 implementation. 
Ho 
a I 


. Copyright (C) 1978 Software Dynamics 
7152- 


.SDOS USER'S MANUAL 


| LOGICAL SECTOR NUMBERS (LSNs) 


LSN's are imaginary sequence EE EE to physical. 
disk Sectors on a disk cartridge or floppy. diskette. The 


. reason for using them is that Logical Sector Numbers can be ` 
mapped onto any disk removing any structure that the disk 


drive might arbitrarily impose from the knowledge and concern. 
of SDOS; i.e., the distinction between tracks, cylinders, and 


Si SOCEOLE ceases to be of concern to ene PDUs file E 


‘The only requirements placed by SDOS on Leg s is that hey | 
begin with Ø and increase sequentially; further, track 0, .. 
Sector 0, cylinder Ø. (usually) maps into LSN 0. "hie is ; 
“because most hardware interfaces can read in this physical - 


disk block as a means for booting the system, so. SDOS . 


. tesetves | LSN D for this: block. 


A useful method for choosing the LSN number for. a disk block 


on cylinder C, track T, and sector S is: 


. LSN(C,T,S)=S+NSPT* (T+NTPC*C) ` 


where NSPT and NTPC are the number of Sectors per Track and- 


the number of Tracks per Cylinder, respectively; where 
“@<=S<NSPT, M=<T<NTPC, and $«sC«NCYL (NCYL= number of 


cylinders). This has the advantage of allowing SDOS to 


allocate new. blocks to a file by use of their LSN's, 


attempting to minimize LSN distance (which minimizes B 
Cylinder, Track,.and Sector distance, in that order). The 


name NLSN refers to the number of. logical sector numbers for 


a disk and is equal to NSPT*NTPC*NCYL. There are physical 


disk read and write routines in the I/O package which are 


required to convert LSN's into the corresponding values of S, 
T and C. Each LSN occupies 3 bytes (maximum of (224)-l 


Copyright. (C) 1978 Software Dynamics 
-153- 


"^ SDOS USER'S MANUAL ` 


J CLUSTERS (LCNs) 


= $DOS allocates disk space in units of "clusters" (not 


sectors!). A cluster is simply a set of sectors whose LSN's. 
are contiguous, and whose lowest LSN is a multiple of the 


cluster size (an arbitrary constant for a particular diskette 


or disk pack). Data placed in a cluster is generally related 
jin some fashion. ` i ' : SE 


Each cluster is assigned à logical cluster number (LCN). An 
(LCN) is the number given to a cluster of sectors. Every LSN 


S in a cluster whose LCN is given by: 


) LCN (LSN) =INT (LSN/NSPC) 


where NSPC is thé number of disk sectors per cluster (defined u 
for the. ca EE ER ge 


The toral number E? clusters on a disk is given` by: 


|NSPC- INT (NLSN/NSPC) 


The special cluster number :FFFF is reserved, and means "no 
cluster allocated" or "no such cluster". This is the value 


_to which a ais clusters specified in cluster headers 


are set. . 


The advantage of this O technique is that it saves 
Space and time. Space savings are effected on the disk 
because each file does not need to explicitly record all the 
sectors it contains. This means less disk space used keeping 
track of disk space. f 


Time savings are effected when SDOS is reading sequentially 
through a file, because (NSPC-1)/NSPC*100% (for NSPC=4,75%) 
of the time, SDOS knows the next LSN which is required 


Without having to do any disk reads to. collect this 
information. The disadvantage is a small loss in efficiency `` 
Of disk storage (i.e., each file wastes NSPC/2 disk sectors 

;on the. averages instead of 1/2 disk sector average). 


The cluster size is chosen to either minimize. average waste 
of disk sectors in files, or to minimize the seek time 
between disk sectors in a cluster, subject to several. 


rsin 


The first constraint is that “all. legal bCN's are limited to 


the range 0-65534 decimal (65535 is reserved; 2 bytes inside 
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posi, i.e., INT((NLSN- 71) /NSPC) «65535. 
“The ‘second constraint is that: one cluster should le enough - 
space to contain all the LCN's defined for a disk, i.e., 


NSPC*NBPS/2 >= INT(NLSN/NSPC) where NBPS is the number: of 


bytes per sector. This constraint allows SDOS to use.a © 
. single cluster to record all the clusters of a file. This 


constraint can be violated, but the result is that a single 


. file might not be able to use the entire disk... SDOS will 
..complain if the Header Cluster of a. file overflows when. 
E E Space to a file. l . l 


The third constraint is that 1<=NSPC<= 255. mie: is purely an. 
implementation restriction and must. be followed. : 


ae Assuming: a file with es 31-2. 1x107 9 bytes, NBPS= $12, NSPC= T NC oS 

we have 2.1%18°9/512=4.2x18°6 sectors in file; =c cz a a 
.4.2x10^6/255-216449 clusters in file. The header: cluster has. 

room for 255*512/2=65286 EE which ‘covers. such a file 
easily. 


To- minimize average wasted: Space. in disk files, 'NSPC shouid 
be chosen to be as small as possible within the constraints 
Specified. This may leave some disk sectors (with high LSNs) 
unused by SDOS if NLSN is not a multiple of NSPC, but the 
total wastage here is again only 1/2*NSPC sectors average, 
and if one has 100 files on a disk, this is insignificant. in 
comparison with the total savings. A final note: if the 
number of sectors per cylinder is not a multiple of NSPC,. 
some time inefficiency will occur when reading sequentially 
through a cluster because some clusters will cross track or 
cylinder boundaries. This inefficiency will be small if the 


average file size is much greater than NSPT*NSPC. 


If the average file size is smaller than NSPT*NTPC, some time 
savings can be gained by making NSPC a divisor of NTPC - this 
will generally prevent part of file (cluster) from U f 


overlapping cylinder boundaries, and will- therefore save seek 


time. 


CUR sample calculation of NSPC: 


Assume we have 77 cylinders (NCYL=77), 1 track/cylinder 


. (NTPC=1), 16 sectors/track (NSPT-16), 256. bytes/sector. 
 .(NBPS-2256) (so NLSN=NSPT*NTPC*NCYL= 16*1*76= 1232). Let 


LSN(C,T,S)=S+16*(T+1*C). Since we have only one track (track. 
#2), the. formula simplifies: x l Se 
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'"ESN(C, S) =5+16C 


For any NSPC>=1 then NLSN/NSPC « 65536, satisfying constraint 
d. 

Constraint 2 nolis 

NSPC*256/2>=INT(1232/NSPC) 

NSPC*128>=INT(1232/NSPC) 

which is true for any NSPC>=4 . 

If we choose NSPC- 4, constraint 3 is also satisfied. 


To minimize average wasted space, we choose NSPC-4. On a 
disk with 180 files, an average of 100*4/2-200 disk sectors 
are wasted. With NSPC-3, with 100 files wastes àn average of 
100*3/2=158 sectors, and prevents files from containing more 
than 1152 sectors (i.e., a partecular file can only cover 938 
. of the Sek © E 
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DISK FILE STRUCTURE 


E File under spos is a mechanism for storing logically 
related information. From the point of view of an 


, application program, a disk file is a very large. array of 8 


- bit bytes which can be read/written sequentially, can be ` 
positioned for later read/writes, and can be automatically 
"extended (at the end) to add more information. These files ` 
can be up to 2731 bytes (2.1 billion bytes) in. size, P 
disk size ‘being the peat limitation.. os 


‘This view of files is implemented by device drivers: The 
+ operations that a device driver considers legal and the 
“actual operation. performed are dependent on each device 


driver. (see Device Drivers). There are two kinds PE. drivers: ` 


 non-disk file and disk file. 


"The disk file "driver. is a component of SDOS e 


handles files by breaking them down into two layers: clusters. 
and sectors. Sectors are the physical unit of transfer 
to/from the disk drive. Clusters are a logical grouping of 
sectors used to minimize the amount of information required 
to record where all the sectors of a file are located. 


Each file has a special cluster ‘of sectors known as the 
Header Cluster. The Header Cluster contains the logical 
cluster numbers of all (data) clusters contained in the file. 
. These numbers are placed in the Header Cluster in such a way 
as to indicate the relative (byte) ot n of. the target ` 


eC TUETET in the file. 


A special cluster number of hex :FFFF means "no data -cluster 


- allocated" to this place in the file. This allows Spar SE 


files to be built with very little wasted space. 
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FIRST CLUSTER POINTER 
POINTS TO HEADERCLUSTER 


--------2------ | REMAINING CLUSTER POINTE 


POINT TO DATA CLUSTERS. 


DATA CLUSTER $0 


Pam Pe "Rep fens ° s ss 


DATA CLUSTER #1 


geg fen Sen (due 0-9 gam Bom fe ú geet 4 Que Cue 


Ü 
I 


gen $e» fo One Gee Pee gen $e fr um 
. 
Quer few Beh pum Qee BD @j Qu j s 


DATA CLUSTER #N 


KE 7 
! ! 
! ! 


The first two bytes in the header cluster are reserved to l 
contain the cluster number of the header cluster itself (this 


simplifies the space allocation routines). 


Succeeding pairs 


of bytes contain the logical cluster numbers of the fth data 


| clusters, ist: data cluster, etc. 


“When a file is first allocated, all the pointers (except the 
: first) in the first sector of the header cluster are 
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2.2 


. Sectors in the header ee are left as garbage. = 


UA special 1 byte counter (stored in the directory), “DIR: l 
(header cluster initialized count) tells SDOS how many of the: 


p TOTE. in the header cluster. are initialized. 


If a data byte is in logical byte Greg "LBN" inj a. ile `. 


then SDOS can access that: byte (in at most two disk reads) ey 


the. following REES EE 


a O e First, compute: I SC 

SE E EE r= NSPC*NBPS `` ` (COMPUTE. 4 BYTES/CLUSTER). 
el : RDCN. im INT(LBN/NBPC) . (COMPUTE THE RELATIVE DATA. 

I Es e e D CLUSTER NUMBER). : 

— Qr RN "HSLSN le +' HCLCN*NSPC 


ae, where HSLSN ` = header sector logical Sector number ` 


_ and HCLCN . - header cluster logical cluster number. |..—— 


This computes the LSN of desired sector in the Header 
Cluster. The "+1" is because the first cluster ` ` 
pointer is the pointer to the header cluster. -The 
"*2" ‘is because each cluster number %° two 
bytes. 


E 


Note: HCSIC may indicate that this sector” (BSLSN) has 


not been initialized! 


Next: Mm 

“read HSLSN into memory in HBBUF E butter) 
 DBLCN zs @((((RDCN+1)*2)MOD NBPS)4.HBBUF) ` 
this computes the LCN of the data cluster containing 

| the byte. | i 
"@" means use the value to the right as a memory 
address and fetch 16 bits.  ".HBBUF" means the 
address of the header buffer. | : 

i Note: DBLCN may be :FFFF (undefined)! 
. Finally: E 


LE | | x 
DBLSN Ze DBLCNÉNSPCAINT((LBN MOD NSPC*NBPS)/NBPS) | 
Read DBLSN into memory; desired byte is. found at. 
s spa ss, RBN ze LBN MOD NBPS `` | 


ES 
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` e d s— e» qe 


| 
x 


! 

i 

MEANS "NO CLUSTER ! 
ALLOCATED" H 
ME H 


a eee À d se: ud 
- - SDOS FILE. STRUCTURE 
! SN » ! 
E cl Š 1 
i A EA = 
1 DIRECTORY 1 
1 _ ENTRY ! 
1 ! 
ls LON ----------- 
1 ! 1 
ae xS š eub 1 
S Sg S i ; 
E: P prom 
UNE O RUE RUE ae ae 
f / 
= == SÉ 
1 
aod 
T f f 
f 1 T 1 HEADER CLUSTER - FIRST CLUSTER OF FILE 
20: "EE X P. B ates : 
rt ooo EE fol ! ! ! ! ! ) (SOME) 
. ! Eod ! ! ! 1 1 )SECTIONS- 
| wie ee me ee dud E? ! ! ! ) INITIALIZED 
1 ! 1 1. bod. 1 l .1 )TO "NO | . - 
l op----- 1 1 fo! ub PPO SPE E ! )CLUSTER 
! 1 | ! ! ' 1 1 1 ! )ALLOCATED" 
q 1 1 3RD l ! feed ! ! 1 )AT FILE 
LEE: ! 1! ! of c ! 1 ) CREATION 
lt sp. 1! 1 PEE ! 1 ! )TIME 
Ud. Lt [ot^ Sch 1 d 
Up que bol bod. ze ! ! 
I l=------> 2ND DATA CLUSTER l 
E w^ i i T A CLUSTER NUMBER OF 
Correo => 1ST DATA CLUSTER | :FFFF 
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initialized as :FFFF (no data cluster allocated). The other 
-. Sectors in the header. cluster are left as garbage. 


AW special 1 byte counter (stored in the directory), DIR:HCSIC x 
+ (header cluster initialized count) tells SDOS how many of the 
-sectors in the header cluster are initialized. € Ze 


If a data byte. is in logical byte number "LBN" in a file, 
then SDOS can access that byte (in at most two disk reads) by 
the following REOL oO ide bint tons l l 


POR E E First, compute: l °. 2p 
Ru deu NB z= NSPC*NBPS (COMPUTE # BYTES/CLUSTER) . 
e í UE -RDCN :- ANT (LBN/NBPC) (COMPUTE THE RELATIVE DATA 


Lear nac UN p CLUSTER NUMBER) | 


mp EE E — ‘header sector ‘logical sector number ` 
I RE and HCLCN = header cluster logical cluster number. 


This computes the LSN of desired sector in the Header 
Cluster. The "+l" is because the first cluster 
pointer is the pointer to the header cluster. The 
ZEN E Ee "*2" js because each cluster number occupies two 
bytes. 


Note: HCSIC may indicate that ‘his sector (HSLSN) has 
not been initialized!! 


Next: ' ME . e 
read HSLSN into memory in HBBUF (header buffer) 
.DBLCN :- @((((RDCN+1)*2)MOD NBPS)+.HBBUF) ` 

this computes the LCN of the data cluster containing 
the byte. 


"€" means use the value to the. right as a memory 
address and fetch 16 bits.  ".HBBUF" means the 
. address of the header buffer. 

Note: DBLCN may be :FFFF (undefined) !! 


d 
1 


Finany: A 25 de a oe GEN E 


EE EE) XT l E oe 
 DBLSN := DBLCN*NSPC+INT((LBN MOD NSPC*NBPS) /NBPS) 
Read DBLSN into memory; desired byte is found ' at 

gs displacement RBN :- LBN MOD NBPS ; MN 
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^. apos FILE STRUCTURE 


4 e l 
1 è E e 
d 1 » pU | 
EC l ! 
4 DIRECTORY `! 
.1 ^ ENTRY l 
b e ! | 
E LCN ----------- 
Ka 
ES E ` P d | e 
ic e Boe 
adde ] l ni 
EE 
a Tf. 
/ 
L. ‘i / 
ES ! 
DEM ! ! 1. HEADER CLUSTER - FIRST CLUSTER OF FILE 
We OY, NSN: |. 
cooles- pol oe ! ! L ) (SOME) ` 
MON. Po’ ! ! ! ! .1. ) SECTIONS | 
[tees ! 1 ! GE ! ot 1°) INITIALIZED 
d ! ! 1 ! ! ! ! 1 )TO "NO 
Lo Lesser poy ! ! Esser ! )CLUSTER 
24 101 I `! 1: 1 ! E ! JALLOCATED". 
4 1 1 3RD 1^ 1 bog ! b 1 )AT FILE 
1 1 1 ! 1 ! ! ! ! Y )CREATION ` 
ee E ! LI ! ! ! ! 1! )TIME 
oo oe ee 1:24 de | ! ! ! 
prog 1! ! Ka ! ! ! 
ded. | | e | 
Sa J d-------»' 2ND DATA CLUSTER S duet 
e > dc PHI | LA CLUSTER NUMBER OF ! 
| [sen------> 1ST DATA CLUSTER ! : PPPE ! 
et eee Any s E ^ ' 1, MEANS "NO CLUSTER ! 
! 4 
! ! 


ALLOCATED" 
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IV HEADER CLUSTER ` 


dun 
Reng G 


i 
i 
i 
1 
i 
i 
| 
{ 
i 
| 


i 
2 wow 
Ge o=o. jw Sun. (om pum: 


$e ome ọm Qe» gen e S 


Logical sector number of lst sector in: cluster = cluster 
number * cluster size in sectors. Succeeding sector numbers. 


are base ` sector. number + index into cluster. : 
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. DIRECTORY.SYS STRUCTURE 


_ The directory stores the name and location of the header 
~~ Cluster for all files on the disk (SDOS allows no magic disk ` 


files which are not in the directory; even pert files are. 


: mentioned in the. directory). 


Each Directory entry is 32 bytes and contains the following 
information: S^ 


DIR:HLCN 


DIR:HCSIC 


DIR: FILENAME 
The file name can be any. left- - justified sequence ore 


letters (uppercase only), digits. @ through 9, $ or 


Ner It may not begin with a "." or a digit: ` The ` EN 


name is blank filled to 16 bytes.- Two file names 
are. considered equivalent if they match byte for: 
byte. SDOS- automatically folds lowercase. 


^ characters in disk file names into üppercase. ^" ^ 


The Header Logical Cluster Number specifies the 
location of the Header Cluster for the file if 
DIR:HCSIC > Ø. If DIR:HCSIC = Ø, then DIR:HLSN is 


actually the cluster number of the lst data 


cluster. 


The Header Cluster Sector Initialized Count. tells 
SDOS how many sectors of the header cluster have 
been initialized properly (see File Structure) and 


need not concern any but the systems programmer. 


DIR:HCSIC is updated whenever a new header cluster 
sector is initialized. If DIR:HCSIC is zero, and 
DIR:NCLUSTERS > Ø, then the file is contiguously 

allocated on the disk, with the first data cluster 
being in DIR: HLCN, contiguous for DIR: SE, 


DIR: NCLUSTERS 


DIR: NCLUSTERS is the number of clusters allocated. 
This count is needed as a very sparse file may have 


an enormous logical file size, and yet have a very ` 


small actual disk allocation.  SDOS updates 


 DIR:NCLUSTERS only when a file is closed. If. PD 
‘DIR:NCLUSTERS is zero, this directory entry is mot. 
“valid and is available for use. by i a new file MAE 


(name). 
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“DIR: FILESIZE ' f mE 

DIR: FILESIZE ` is the Re size of the file in 
bytes, and is equal to the position of the last 
data byte written in the file, +1. The filesize is 
completely indepengent of sector or cluster ` ‘size. 


DIR: PROTECTION l "wi l f 
. DIR:PROTECTION contains file protection bits. The | 
protection bits prevent inadvertent or undesired: 
references to file. The currently defined bits 
are: i f 


PROTECT:DELETE ` 
- PROTECT:WRITE 
"KNOT DEFINED? 
«NOT DEFINED» 
. «NOT. DEFINED? 


i 
i 
i 
1 
i 
i 
i 
| 
I 


<NOT DEFINED> 
«NOT DEFINED» 
«NOT DEFINED? 


SHEN WAU OY Y 
| 
| 


PROTECT:DELETE 
The PROTECT:DELETE bit — E DELETE, RENAME, and ` 
a l CREATE commands on a file with the corresponding 
poue f name. This is used by SDOS to prevent accidental 
ca erasures of critical system files, and may be used 
by the user to protect his erat teal files. 


LJ 


PROTECT: WRITE , 
This prevents user programs from writing data into 
the file. E 


Dike CREATIONDATE. 
DIR: CREATIONDATE contains the creation date of the 
file in the form DDMMYY. DD is one byte containing 
the. day number in BCD; MM is one byte of BCD month; 
and YY is the year number modulo 100 in one BCD 
byte. 3 l 


`: SDOSDISKINIT sesar EE the first data cluster of the 
directory at INT(NLCN/2) (the middle of the logical disk) in 
an attempt to decrease seek-to-directory time. This also ` 


^.causes SDOS to extend the directory in the middle of the disk ~ 


." if need be. Note: This LCN must be non-zero! (Otherwise, ` 
Uthe directory and the boot cluster collide. ) 


apos locates the directory initially by reading BOOT: DIRLSN ) 
from the BOOT.SYS file.  BOOT:DIRLSN gives the LSN of the  : 
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directory sector containing the DIRECTORY.SYS entry. ‘The 


directory entry for DIRECTORY.SYS is located in the first 32. 


bytes of the sector. This requirement also forces the sector: 


‘size to be at least 32 bytes (the first entry must be 


cohtained entirely in the first directory Rectory and to BE 


a multiple of 32! 


All ‘other filenames in the directory are: - added to it 
according to the following procedure: 


‘The. directory is searched by initially hashing the desired 
“name to choose a directory sector, and then searching 


circularly through the directory for the desired name. The 


‘hashing scheme tends to make lookups of existing names very ` 
quick, as long as the directory is 88% or less loaded. -The 
circular search guarantees that even if the directory size. 
changes; files will still be found. 


The directory is automatically expanded SH SDOS if it is full 


and a new filename needs to be added. This automatic: 


expansion invalidates all the previous hashes, but since new 


(or renamed) files will get hashed to the correct place, 
after the system has been used with the expended directory 
awhile, lookups will speed up. again. 


The directory size is kept in the DIR:FILESIZE entry of the 
DIRECTORY.SYS entry, and is always a multiple of the cluster 
size (NBPC). . l 


Ae a convenience to the hashing algorithm, a limit of 65536 


directory sectors is imposed on the DIRECTORY.SYS file. 
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X S 
E en p 
l e 1 
! ` ! 
EE a I L============== =s 
.. DIRECTORY. "duo Ng ! 16 BYTES, me 
ENTRY ` : 1 DIR:NAME ! LEGAL NAMES CONTAIN 
: . 1 ! A-2, GE 9, S, RH Us E 
Do e e ae ae ee ee l i 
1 PIR? HCN ! 2B, "HEADER CLUSTER NUMBER 
i T 
i: M 1. 
eege ! 
eae + DIR: FILESIZE ! A8, NUMBER ` OF BYTES IN 
E ! THE FILE 
[sasa a eee ! Ee 
! DIR:PROTECTION ! 1B, PROTECTION BITS 
! k | | | 
Pies as ema e SS L I 
! “DIR:HCSIC ! HEADER CLUSTER SECTOR 
aa e ! | INITIALIZED COUNT. — 
Ñ I-—--- e TN T P 
! DIR:NCLUSTERS ! NUMBER OF DATA 
l ! CLUSTERS IN FILE 
De aee aome ne 1 i ; 
IDIR: CREATIONDATE! 
! 1. 
d ! 
l ======s=s========1 
1 - * 1 
H v H 
i s ! 
4 ! 
l l 
i ! 
! L 
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FIXED IN 1ST SLOT ` E 
SIMI as | 1 | bc 
N ! ` of 
AS 1 DIRECTORY |! 
Nea V E 
No o 1 
ENG 1 1 
A . .IDIRECTORY! | |! | 
=--> 1 .8Y8  ------------- i DIRECTORY 
ee E eg I ! ! V HEADER. CLUSTER 
LO HASHED. ---------- > | SDOS.SYS! l oo 
Gë I s l- ! Pame] pr to 
! ! le Ve ea e 
-——— b. l ! Liesl p 
! fe de -LCN CN =@ (DIRECTORY) - st, 
SS is V . 4 DISKMAP !- (PROBABLY) 
aaa, Pi SYS A «ec HASHED. i 
spos{! «al Do 0------------------ ! 
FILE(! ! I !  ! ! ! Wi 
{r ! ‘ E: a m m e 
! 1 ! ; ! ! seat 
ND. /N : ! . ! ! pou 
"Y | / -T-——----- ` OTHER ee ge ee, 
n VEM PE, ENTRIES ! 
/ ee ud VARIABLE ` | V 
a a a a a 
-T---------- ! IST CLUSTER ! 
! | ! ! BIT MAP OF i 
121.4 04-11 ! AVAILABLE ` ! 
! CLUSTERS ! 
! 


SDOS hashes to lst directory entry, and does linear circular 
search thereafter. I 
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EE m oad w DISK | | 

ems IR o em dese Qe l- BOOT.SYS 
. LOGICAL SECTOR 0 ---------- ! | iv 
E ACIE E dd 

tom ves Vv 


e i i ECT N f 
PA i MUN N | SH 
/ | I S N <===LOGICAL CLUSTER #1 
es gu eg Ee N D \ <=-ECN 2, ETC.. 


N SN 
a d 


I 4«-------CLUSTER 4 NLCN/2 = 
! ! © L 1ST DATA CLUSTER OF 
/: "e f DIRECTORY.SYS (Typical) 


n = oe Pree = - NO š P 
porc 
s = = 


\ 
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Í: 


i ` “poor, sys is a. file which, contains LSN: d (the boot sector). 
"Phe. BOOT. SYS file contains three things: | 


US )) a disk 3dentitjostion (32 bytes of text blank padded). 


2.) the appropriate DISKINFO (tuning parameters). for this 


. disk 
. 3.) a "simple" program to read SDOS. off the disk and into 
memory as a means of IPL'ing. 


Items 1 and 2 are stored in fixed places in LSN B. and | occupy 
— "the first 64 bytes. This sets a minimum. sector size. 
"requirement of 64 + 1 --> 128 (sector sizes must be a | power 
Of twol). -Other LSN'S in the BOOT.SYS file are simply wasted. 


Or used to Store an extended bootstrap program if needed. I 


_ The form of the boot sector must be as follows: | 


B | e | 
16 BYTES ! JUMP ----------- THESE BYTES ARE 
ANS ! ! | | USED FOR ANY . 
! ! .1 PURPOSE BY IPL ote 
"15 BYTES ! DISK 1 ! OR BOOT ROM QUT ER 
! INFO ! ! ROUTINE | : 
X ! b ! RE | 
l BYTE !DISKINFOCKSUM ! <------ = ¿FF - SUM OF 
Ano ! ! 1 BYTES IN 
! TE ! DISKINFO PART 
! Í ! | 
! ! ! 
32 BYTES ! DISK ! ! 
! ID T ! 
ki ! up 
! ! ! x 
!. ! 1 | 
! L A 
d «--------- : 
-— IPL 1 | 
. REST OF ! ROUTINE n | 
C7 SECTOR  ! 1 | 
pL Uu ! l 


This ensures that the disk identification string is easily 
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Gë JlocataBle,- and that. it does not prevent the IPL. routine from 
S A Cad 


Normally, LSN D HEN “read “into memory et $190 bo & ROM boot 


routine, and control is passed to location $100. . 


The IPL routine must res ‘the contents of the SDOS- file into 
- memory at the appropriate place, and es! control to the 
+ Stenting point. ; 


s BOOT: FILESYSTEMVERSION is a single byte containing a file 


System version and revision number in the left and right 


~ nibbles, respectively. This document describes. file system ` 
“version l.1 (note: SDOS revision numbers 20 not r SEREIN: 
match file "ersten revision number st). 


BOOT: :NSPC is a ‘single. byte whieh s the cluster size. 


of clusters on this disk (8<BOOT: -NSPC<=255). 


|. BOOT: MINALLOC is: two bytes which: specify the minimum number 
` of data clusters to allocate to a disk file when it is 


created on this. disk. D is not legal. 


 BOOT: 'MIDALLOC is two bytes which specify the minimum number 


of clusters to. be allocated to a file being extended. 


BOOT:MIDALLOC must be >= 1. 


-BOOT:MAPALGORITHM is 16 bits which are used in a disk-sector 


driver dependent way to tune rotational and seek. latency 


|" times to a minimum. 


Commonly, the upper 8 bits are used as "spiralling", or the 


number of sectors each cylinder should be offset. from the 
next (cylinder) to tune seeks for sequential reads; the lower 
byte tunes the physical spacing between adjacent logical 
Sector numbers (also measured in units of sector times). 


SDOS can usually only read every other sector, best case; 


When using the "common" mapalgorithm interpretation to map 
LSNs into physical CYLINDER, TRACK, and SECTOR (assuming 
CYLINDERS and TRACKs increase sequentially from 8, and 
physical sector £ on. all TRACKS are aligned) the following 


ON formas apply:. 
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REM | . PSUEDO- -BASIC TO COMPUTE PHYSICAL CYLINDER, 
TRACK, SECTOR 


| CYLINDER= INT(LSN/(NSPT*NTPC)) — 
- PRACK= INT((LSN- CYLINDER*NSPT*NTPC) /NSPT) 


SECTOR- ((CYLINDER*SPIRAL) +MAP[LSN. MOD NSPT]) MOD NSPT. 


where MAP[i]- (i*SPACING) MOD NSPT if SPACING is relatively 
MEE prime to NSPT, and is generally computed as: 


"MAP[0]:- Ø N IRULE! 
K= SPACING 
FOR i= 1 TO NSPT- 1 
100. FOR J= £ TO i-1 
| IF K= MAP[J] THEN K= (K*1) MOD wee GOTO 100 
NEXT J `` 
Ee [i] = A ; 
së = (K+SPACING) MOD NSPT ii 
E i 


On hardware Systems where formatting a disk is used to effect 
this tuning, the Mapalgorithm is by convention always set to: 
"lI". i 


BOOT:CREATIONDATE is the date that this disk was 
SDOSDISKINITed, and consists of 3 BCD bytes: Zei: month,. and 
year MOD 100, respectively. | 


BOOT:DIRLSN is the Logical Sector Number of the DIRECTORY.SYS 
sector that contains the DIRECTORY SYS directory entry in the 
first 32 bytes. 


BOOT: CHECKSUM contains :FF-[sum of the 15 bytes Between (and 
including) BOOT:FILESYSTEMVERSION] moduio SE and is used to 
check the validity of the disk. 


BOOT:DISKID contains 32 ASCII characters blank filled, used 

solely as a disk identification. This ID is displayed by the 

FILES command. It can be used (read) by an application for 

the purpose of verifying the disk before the application uses 
it. 


The IPL TR is used to read the cohtents of SDOS.SYS into 
memory. Ususally, the IPL routine does not fit entirely into 
- the remainder of the BOOT sector; the rest of the IPL routine 
. is stored in. memory image format in the remaining sectors of 

LCN 0. Listings of the IPL routine can be obtained from the 

E distributor of SDOS : or from Software, Dynamics. 
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|. SDOS. SYS 


SDOS. sys is an  SDOS load record format. file containing the 
- "memory resident part of the operating system. -It is used by 


the BOOT procedure ‘to load a copy of the system. from rne: urs. 


into memory. 


To simplify the boot process, certain restrictions are made 


on the file Structure of SDOS.SYS. 


^"The data LCNs of SDOS must be numbered 1, 2, 376s Etc., 


i.e., a contiguously allocated file. This guarantees . 


- sequentially increasing LSNs which makes the BOOT routine's 
^job (of computing LSNs) extremely simple. ‘The header LCN of 


SDOS (if it has one) may be anywhere on the disk; the boot 
routine need not look at it. (many boot routines never bother 


"reading. the SDOS header clusters). Normally, the - 


SDOSDISKINIT program assigns a EE Pah LCN to the header 
cluster of SDOS.SYS. ` f E 


. The start address of SDOS. SYS- is defined to be SYSCALL$ 
(: FB). 


When debugging a (newly SYSGENed) 1/0 package, a convenient 


trick is to modify the first load record (actually the start 
record) in the SDOS.SYS file so the SDOS start address is the 
entry point to the ROM debugger instead of :FB. With this 


change made, "booting" will cause SDOS to get loaded, and the 


debugger will then gain control. . Patches may be made and 
breakpoints established, and then SDOS can be started by 
causing a jump to :FB. When debugging is completed, the 


first load record should be restored to its initial state. 
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DISKMAP.SYS |. x 

The DISKMAP.SYS file is used to keep track of clusters 
allocated to disk files for that disk. Each disk da 
or floppy diskette has its own DISKMAP. SYS. 


The file has one bit per cluster on the disk on which the 


file resides. An "on" bit indicates the cluster is allocated 
(or contains a bad. Sector). An "off" bit indicates a free 
cluster, available for allocation to a file.  SDOS assumes 


that the entire disk map can be contained in a.single . . TE 
cluster, so if constraint 2 of LCNs is violated (see section 


on CLUSTERS), one needs to make sure that 


. .NBPS*8*NSPC>=INT(NLSN/NSPC). If constraint 2 T satisfied, s 
80 is this condition (the 8 is the number of bits per byte). 


Each byte of DISKMAP.SYS. represents 8 clusters, such that bit. ` 
“number n (starting with 0, counting from the right) UR 


represents an LCN such that (LCN mod 8) = n. Bytes at 
logically higher byte addresses within DISKMAP.SYS represent 
groups of LCNs with higher values, so that if LBN (logical 
byte number), BITN (bit number) represent a particular bit in 
the DISKMAP.SYS, then that bit corresponds to LCN= LBN*8+BITN 


(logical - cluster number). 
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BYTE $0 
. $1 
$2 


! 
1 š 
ONE CLUSTER ` 
! 
! 4 
B 


NOTE: SECTOR - 
CONTAINING BIT 
FOR NLCN-1 IS ` 
NULL FILLED WITH 
l'S TO MAKE IT 


.. APPEAR THAT THE 


ILLEGAL LCNS  . 
ARE ALLOCATED. | 


allocated cluster number 
a Search for a free cluster. 


SE yIITIITITTT 


DISK CLUSTER ALLOCATION MAP 


1 


* 
1 


1 
i 
1 
1 
1 
1 
! 

4 
1 
1 
1 
! 
1 
1 
! 
1 
! 


1⁄/////////1 


VAAL E 


1⁄////////////! 
1⁄/////////////////////! 


1⁄/////////////////////1 ` 
1⁄/////////////////////1_- 
1///////Y1LLEGAL////////1 


1///////CULUSTER////////! 
1///////NUMBERS////////1 


!⁄/////////////////////1_ 


!⁄/////////////7////////! 


1⁄/////////////////////! 


ee LEE S A 


A nl" bit --> cluster. is busy 7 
! A "B" bit =--> cluster is free (available). 


LSB. ‘CORRESPONDS “TO 2 
LOGICAL CLUSTER +0. 


«--LOGICAL CLUSTER 48 
<=-#16 i 
3 €--424. 


---NLCN- 1 (MAXIMUM . 


LEGAL CLUSTER NUMBER) 


Clever space allocation is done by taking the need r f M aes 
(to a file) as the starting point of ` 
Searches toward logical cluster. . 
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number @ and NLCN-1 are both made in an attempt to minimize ` 
the distance between the cluster number (allocated to the 

"preceding cluster in the file) and the new. Furthermore, an. 
old cluster number of :FFFF causes allocation starting s a 
random place within the map. 


The allocator prefers a forward: Search; and will. not bother 
with a backwards search if it can get a distance o 1 between. 
the old cluster number and the new. 
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. ERRORMSGS.SYS (ERROR MESSAGE FILE) FORMAT: 


The ERRORMSGS.SYS file is used by SDOS to convert 16 bit 
error codes into English text messages for. the operator. 
“The dile must exist on drive ð, and drive g must be mounted, 


». in order for SDOS to use the file (otherwise SDOS merely 
| prints "Error nnnnn"). 


‘The file is organized into two parts, and is sparse. 
‘The first part of the file converts 16 bit error codes into 
, String pointers into the file. The second part of the file. 
a contains the raw error dead text. 


the 16 bit error code is multiplied by 3, and used as a byte. 
index on the file to fetch a 3 byte relative. index jinto the. 


file. The 3 byte index points to an ASCII error message 


“string, ending with a CR (:@D) character. The SDOS error 


routines do not print the CR explicitly but'use it only to 
decide where the end of the error message is (see 
SYSCALL:DISPERROR). A 3 byte index value of zero means "no 
message defined". 


The first 65536*3=196608 bytes of the file are reserved for 


this lookup; since the number of error messages actually 
defined out of the 65536 possible is very small, this region 
of the file is sparsely allocated. The first text message 


Starts in byte number 65536*3 of Ehe file. | This section of 
the file is dense. 


New messages are added to the file by merely appending them 
to the end, and adjusting the 3 byte pointer corresponding to 
the error,code to point to the old end of file. 


The program ERRORMAINT is used to maintain the contents of 
^. this file. The file ERRORMSGBUILD.DO is a DO file used to 
|: initially construct this file. 


| ERROR MESSAGE NUMBER ASSIGNMENTS: - 


op | NO ERROR | 

"D ^ ^ |, OPERATOR REQUESTED ATTENTION 

299. > |. BASIC COMPILER RUNTIME ERRORS prar 

100-199  . ^. ERRORS RELATED TO SYSTEM PROCESSORS, ETC. 
7208-299 EDITOR ERRORS ` 8 
..300-999 . . APPLICATION SYSTEM DEPENDENT ERRORS 

. 18000-1999 . SDOS / I/O ERRORS | 


| 20090-65535 RESERVED 
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‘The ERRORMAINT Program 


The ERRORMAINT program is used to manipulate the 


ERRORMSGS.SYS file. Commands are provided for: examining, 
changing, deleting, and adding error messages. This program 
will create an Ee PORNS GE: SYS file if one PoR, t already 


< exist. 


There is a special DO file called ERRORMSGBUILD. DO which will. 
create an ERRORMSGS. SYS file and insert all the standard 


: “system error messages. To use this standard procedure, 


simply type: 


` «DO ERRORMSGBUILD. DO: 


` on the consoles This. procedure uses the ERRORMAINT program 
p EO Actually. build. the. file. | 


For non-standard messages, or for changing/adding/deleting 
messages in the file, the ERRORMAINT program is used. The 


command, for this program are given below. 


Create new ERRORMSGS.SYS file 

View (examine) a message 

Insert a message (replaces old message) 
List messages, from message number to message 
"number, on console 

Delete a message. i l 
Output messages, from message number to 
.. message number, on file/device. 

S Stop, exit to command interpreter 


¿00 < 


Each Command is typed as a Single letter followed by a 
carriage return when the program presents its prompt '>'. 


The program will prompt with questione when additional 
parameters are needed: : 


: 
1 
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"used to keep track of I/O paths to files, so there may be 


^ several IOCBs associated with: an. FCB,- d. ee, when 


file is open on two channels). 


xs same ` 


The FCB tells SDOS where Ë ë file is ona disk, whether. the 


P .file is newl 


y created, simply opened, or deleted; 


the size of 


the file, number of allocated clusters, etc.. Having. all this 


information in one place for a file means it can be open for 


. update and/or expansion. on ševeral I/O channels, and am 
expansion or deletion operation on one channel will be 
automatically noticed. on other channels because the. FCB. is. 


- "shared. 


that file so 
accomplished. 


if directory: upüeting is Aire 


— Aso -the--FCB- -contains-a pointer to Ehe. directory ‘slot for: 
SE it is easily 


_ All open files, EE the directory, the diskmap, and the 


error file a 


re recorded in FCBs. 
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BUILDING A TURN-KEY APPLICATION SYSTEM 


| Inm many. circumstances, the full generality of an E 
- development system is not needed; a simple menu-driven 


application program selector plus the applications. is- 


Sufficient.. This is useful in an office. environment because . 


it- reduces the training: ‘required of the office personnel. 


Only two things need be done to build a turn-key application 
on. 


Ww or The boot process. meds to be made automatic. This ` 
x. procedure. is hardware dependent. and is not. described further 
weg here. M oea cT O EIS | | 


2. ) The DEFAULTPROGRAM on an otherwise bootablé SDOS disk 


= "needs to be-replaced-by the menu-display program: ` “This 


program may contain the entire application, or it may CHAIN 

to other segments at the appropriate time. The other <. e 
segments, on. completion, will EXIT, which causes. 
DEFAULTPROGRAM (the menu- display program) to be EEN ge 
the cycle repeats. 


Note that the application program must set the time and date 


itself by doing a WRITEB to the ae device. 


"System development can still continue on a turn-key system if 


the menu program has a way of chaining to SDOSCOMMANDS, or if 
a regular development disk is inserted (just. the boot part is 


automatic). 
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1/0 PACKAGE ` 
"This section describes the 3/0 ‘package part of. SDOS. 


The 1/0 package customizes SDOS to the local ehvironment. de 


contains drivers for the various devices; it contains disk 
sector read and write routines; it contains information ` 


| allowing SDOS to control the interrupt system, locate the 


system debugger, and it contains. the buffer space used by all 


Be drivers. 


This section describes each of the different parts of the 1/0 


“package in some detail. Examples are given.. Symbolic. 
"definitions of all assembly language labels defined in this 
"section of the manual-can be found. in the file U 


^—. SDOSIOPKDEFS. ASM. 


“First, we give an “overview of how SDOS does 1/0. 
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 SDOS INTERRUPT SYSTEM PHILOSOPHY 


SDOS interrupt system. Naturally, this view is colored by 

Characteristics of the 6808 hardware, and, in particular, the 
Specific manufacturer's implementation of a 6800. computer- 

. System. ` ` i : is i : NS E 


` This section gives the philosophy of the software part of any 


The interrupt system allows multiple I/O tasks with nested, 
priority interrupts.  Timeouts prevent programs from hanging 
up on I/O devices. us SS € pude E I Se 


Execution of a particular sequence of programs is done by ` ` 
. "tasks". A task is literally an execution of a program that ^. 
can wait for some event, or be stopped and started by the 

"Scheduler". Several tasks can simutaneously exist, each in 


.its own state of execution or waiting. One task is dedicated. ` hiis 


to.execution of the user program; this task is known as the ` 


user task. The user program performs I/O by issuing SYSCALLs ` -: 


which cause the user task to eventually execute an I/O driver 
routine. The I/O driver stores information describing the 

. I/O in a table it shares with the interrupt routine for that 
device, and then causes an interrupt to activate the 
interrupt routine. The interrupt routines process. the: 
interrupt. 


The SYSCALLs simply switch the user task to the proper I/O 
driver after some "reasonableness" checking. 


The I/O driver is responsible for interpreting the specific 
SYSCALL and setting up any data tables, or queues needed by - 
the interrupt routines to perform the desired I/O. In many 
cases, the I/O driver will cause the user task to wait for 
the completion of some operation being performed by the 
interrupt routine for that device before setting up tables, 
etc. Generally, the I/O driver itself needs to do no àctual 
I/O (i.e., any loads, stores, or tests of peripheral device 
registers). | | | 


The interrupt routines for a device perform all the physical 
I/O (loads, stores, etc.) to the device (registers), using 
the data set up by the I/O device driver. The interrupt 
routines also signal completion of an operation and: readiness 
for another operation to the I/O device driver so that any `` 
Waiting task(s) may continue setting up data required for 

. 1⁄0. ae ae Më e : : ao 
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INTERRUPTS 


“when an interit occurs, the 6800. microprocessor saves the 


current context on the stack and transfers to an interrupt 
routine. At this point, interrupts are off. The interrupt 


routine is required by SDOS to switch to a new stack if this 
is not a nested interrupt. This scheme obviates the need for 


any tasks to allocate stack space for nested interrupts; a` 
special interrupt stack is set asine in the ae Pagkage: for. 


Ah. purposes 


V A. (Single byte) counter, SDOS: STACKSWITCHED, is used do P 
track of the interrupt nesting level. ` If the counter's value - 


is -1 (:FF), the stack in use is that of the currently 


"executing task, and must be switched when an interrupt 
occurs. Each time a (nested) interrupt occurs, the counter. QUSS 
— is .incremented..by.one; so. the counter. always. contains-a-value- = is nesi 
. equal to the number of nested interrupts minus 1. The 


counter.is decremented on exit from an interrupt routine, and l 


` Stacks re- -switched if the interrupt stack is empty. 


It is assumed that no more than 127 interrupts can be nested, 
(i.e., the counter can never be incremented from :7F to :80). 
Switching stacks is required only on the first of a nested 

set of interrupts, and requires the interrupt routine to save 
the current value of the S register in the task control block 


Selected by SDOS:CURRENTASK; then the S register is loaded 


with a pointer to the end of the reserved interrupt Stack 


.area. Stack switching need not be done by an interrupt 


routine that pushes no data onto the stack, and is not 
interruptable; this usually occurs only in very rare. 
circumstances. and normally stack switching is always included 
with an interrupt routine. Stack Ge occur before ^ 


e interrupts are re-enabled. 


The code to effect a Stack switch is as petites: 


o INTERRUPT VECTORED TO HERE 
SS INC SDOS+SDOS : STACKSWITCHED 
BNE ^ .INTERRUPT: POLL 
-LDX |. SDOS*SDOS:CURRENTASK ` 
STS  .  TCB:STACK,X 
Ax LDS >~  INTERRUPTSTACKTOP T 
_ INTERRUPTPOLL EQU. ian DECIDE WHICH DEVICE i 


SE THE INTERRUPT 


| As. a convenience to 6800 systems which use the Standard 6800. 
| interrupt system the IRQ vector can be aimed at 
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.. SDOS*SDOS: IOINT, which contains this stack switching code. 
. SDOS: IOINT jumps to the location specified by CNFG:IOINTPOLL ` 


after switching stacks, where code must exist to determine | 
which device caused the interrupt. , SDOS: IOINT is Doe 


only as a. convenience, and need not be used. 


A 'possibke method. for exiting an interrupt routine is as dh 


follows: 
NOP : (IN CASE. INTERRUPTS WERE ENABLED... 
SEI J TO ALLOW NESTED INTERRUPTS] 
DEC SDOS+SDOS: STACKSWITCHED 
BPL DORTI 
LDX ` SDOS+SDOS: : CURRENTASK i 
.LDS Gen STACK, X 


-DORTI . EQU 


RTI... 


This is essentially the code suppired by the SDOS entry 


- point, SDOS:RTI, except that scheduling is forced if any. 


nested interrupt routine ‘signaled an interesting event. 


The interrupt stack must have shandi space to handle the 
total sum of all pushes by all the possible nested interrupt 
routines, plus room for a context block for each f 
interruptable interrupt routine, plus space for an NMI 
context block (for debugging) and some space for the 
scheduler to use, “This total space requirement is needed for 
the rare case that all the interrupt routines interrupt each 
other at the worst possible time (in terms of stack usage), 
and an NMI occurs in the most deeply nested routine. 


once stacks have been switched, the interrupt routine will 


probably need to poll the various hardware I/O registers to 


determine the cause of the interrupt. Some 6800 systems have 
Special vectoring hardware that vectors to a unique location 
for each device; this system saves the time required to poll 
(Note: a copy of the stack switch code must be present at 
each of the vector points in this case!). With the cause of 
the interrupt determined, the u EDE routine for the 
appropriate device can be executed. 


| The interrupt routine: for a device jis E for 

^. effecting the actual device data transfer and is totally 
“device dependent. ‘There are only two properties of a device 
-interrupt routine that SDOS affects: how the routine handles 


nested interrupts; and communication by the interrupt routine 


to any task(s). 
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A device interrupt routine may allow nested interrupts by 


..re-enabling the interrupt system (usually, via à CLI ©. |. 


instruction) (SDOS:STACKSWITCHED will keep track of interrupt 


nesting if it occurs). Re-enabling interrupts can only be 


allowed if no further interrupts from the device will occur 


^." while the interrupt routine for that device is still active 


(or much confusion may result!). An interruptable interrupt 
routine must disable interrupts before un-switching stack 


pointers. For short interrupt routines, re-enabling 
interrupts usually does not improve system performance. 


There are generally two kinds of interrupt routines: 
.Single-state and multi-state. Single state interrupt ` 

routines are generally used for serial terminals,: line S 
- printers, and other devices in which only a single step is 
required for each I/O operation. Multi-state interrupt 


— — routines are. used whenever several steps are required for => 


each operation (i.e., on a floppy disk controller, a step may 


be required to move the heads, another step to wait for the 
desired sector to come under the heads, and a final step to 


actually read or write a data sector).  Multi-state interrupt 


routines are coded much like a task level routine; each step 
is performed, and then the interrupt routine waits (for a 
completion interrupt) before proceeding on the next step. 


Single-state interrupt routines require no special tricks and 


So are not further discussed here. 


A Multi-state interrupt routine is one in which only a part 
of the entire interrupt routine is executed on the first 
interrupt; another part executed on the Second, etc. At the 
end of execution of each part, an operation is issued to the: 
device, and (logically), a wait for completion of that i 


Operation is performed (no "wait" is actually performed; what 


really happens is that the interrupted program is allowed to 
continue). Completion is signalled by another interrupt, 


“which causes the next part of the interrupt routine to be. 


executed. Usually, each part of the interrupt routine knows 
which part of the interrupt routine is to be executed next. 

s l Ge . j . EE 
Multi-state interrupt routines; are conveniently implemented 


“via a dynamic pointer which is set at the end of execution of 
..each part, to point to the next part. E 


An “example is included here: 
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| INTERRUPT EQU  *.. | 
R. eet s SWITCH STACKS 
vw B I TEST DEVICE 


 B-- JUMPNEXTPART — IF THIS DEVICE CAUSED INTERRUPT 
JMPNEXTPART EQU * ` 
a FCB | $7E,0,0 


INTPARTl . EQU  * 


2.  SIART NEXT. DEVICE OPERATION 
JSR KR ss 


pU po NEXT DEVICE OPERATION ` 
JSR WAITFORINT ` 


.. WAITFORINT So A 


PULA ` 

PULB ` ; 

STAA JMPNEXTPART+1 
. STAB JMPNEXTPART+2 


* .-  .-. ^RETURN TO INTERRUPTED PROGRAM 


Tasks signal the presence of data to be processed by an 


interrupt routine by a combination of flags and a STARTIO 
interrupt. Tasks never do actual stores or loads to device 
registers; these operations are left for the interrupt 


. routine. 


A task Betting. up an 1/0 operation builds an I/O block (of ` 
data) (usually in the device DCB) to be inspected by the 
interrupt routine. A single byte flag (or counter) 
associated with the I/O block prevents the interrupt routine 
from performing this inspection until the construction is 
complete. The task building the 1/0 block is responsible for 


— setting the flag (incrementing the counter) (never resetting 
. it); the interrupt routine clears the flag (decrementing the 


counter) (never. sets it) when processing or that E piock bY 
Pae interrupt routine is complete. ` 


The interrupt routine cannot inspect the 1/0. block (s) unless 
Jr is awakened by an interrupt. To prevent the. possibility 


of no further interrupt expected, and a task waiting for an. 
I/O block to be inspected, an INTERRUPTEXPECTED flag is” 
associated with each interrupt routine. The interrupt 


routine sets or clears this flag depending on whether it 
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expects another snterrupt or not. Whenever the daterpube 
routine finishes processing one I/O block, it checks other 
1/0 blocks associated with it to determine if any of those 
blocks are ready to be. processed; if so, then processing ie 


‘continues and the INTERRUPTEXPECTED flag is set (or left 


set); otherwise, the. INTERRUPTEXPECTED flag is reset. 


After: a ask sets the "I/O block ready" flag, it inspects the 


INTERRUPTEXPECTED flag. If the flag is set, -the interrupt 


routine will eventually discover the 1/0 block and process 


it; the task need do nothing further to cause the I/O to 
occur. . If the flag is reset, then there is a possibility 


that. thè “interrupt routine has not “seen the. newly-readied 1/0: 
block; the task then causes an interrupt via the SDOS:STARTIO 


routine. This interrupt causes the interrupt. routine to look 
for ready 1/0 blocks. ` "m 


The. task can determine. when the I/O operation on. the rop 
“block is complete by waiting for. a flag associated with the : 


I/O block to get set by the interrupt routine. 


In many cases, a counter associated with a Siedler buffer is 
a convenient substitute for a set of I/O blocks with 
corresponding flags. 


An interrupt routine signals completion of an I/O operation 
to task by merely setting a flag or incrementing a counter. 
Tasks waiting for I/O complete do so by waiting for a ` 


particular memory location to be non-zero. A typical 
interrupt routine will have a DONE flag and a status word; 
completion of the I/O operation causes the DONE flag to ce 
set and the status word to be updated to reflect the 
completion status. When a task waiting for the done flag 
wakes up, it can inspect the status. The part of the 
interrupt routine that receives an interrupt from a STARTIO 
operation must clear the DONE flag: I | 
An interrupt routine must exit to SDOS: RTI if ho upa sss 
activity occurred (i.e., it did not signal completion to a 
task) or if the signal was of low enough priority so that a 


relatively. long wait before a waiting task discovers the 
“signal will not hurt. If an interesting event | occurred that 


needs priority. processing by a task, the interrupt routine 


~ must exit to SDOS:RESCHEDULE, which will cause task f 
“rescheduling.” ‘Both SDOS:RTI and SDOS:RESCHEDULE unswitch the 
Stacks properly.so. that. this need not. be done by the l 


interrupt routine. 
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. Timeouts are used to perform long-term timing and/or aborting 


of.I/O operations initiated by an interrupt routine. 


Essentially, a timeout causes a guaranteed interrupt, even if” 


the device itself, for some reason, does not. An interrupt 
routine, on receipt of a timeout interrupt, can retry the 
operation or mark the I/O block for which the I/O was 
initiated as "TIMED OUT", and signal completion of I/O on 
that block. At this point, the interrupt routine is now 
ready to start the next I/O operation.  SDOS provides a' 
standard mechanism for implementing timeouts. - if 
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\ + NORMAL 6800 INTERRUPT HARDWARE 


EE 
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l ! ! Control 
as esa 
— o4 IOINT ! ! 
Pepa = >1ZZ71Switches i ! 
i © (02 1///A8tacks if ! 
-———— !///!Necessary ! 
p =-~! i 
d I l SDOS. l 
: I d p 1 ! ! 
. =————-1IOINTPOLLI | ! 
Wo mm] : t! ! l j ! 
4 t... t ! SDOS:  SDOS: ! 
V V 1 l 1! RTI RESCHEDULE! 
TN f i E à i 
N v E RUE ME ES 
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Vectored Interrupts . 


! ! ! 
e l- USER. 1 
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1 1 ! 4 ! KL ree 
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| Vo ! a 
; l GE Ñ 
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l interrupt! ! os 
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! ! 1 ^ Back to 
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AS NET 
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 SDOS ENTRY POINTS 

— The SDOS entry point table contains entry points to SDOS — 
routines and the values of certain variables needed by the 
I/O package. 


mie Cable physically starts SE Ee d of the ` 
permanently resident part of SDOS. All entries in this table 


SDOS:XXX in the definitions file, and are meant to 


be accessed directly via LDAA/JMP/LDX SDOS+SDOS: XXX | 
instructions, where SDOS is a symbol whose value is the base ` 
of tne permanently resident. portion. 
The entry points are described here. 


| SDOS: VERSIONNUMBER 


This byte contains the hex Se of the 
version number of SDOS, with the leftmost 4 bits 
being the major version number, and the right 4 
bits being the revision number. An 1/0 package. 
coded for a particular revision of SDOS should 
check this byte, as the I/O package interface is 


. very likely to change from revision to revision. 


DOS LASTERROR 


SDOS:LASTERROR is the last 16 bie: error “sumber of 
the error that SDOS handled or reported. This is 


most useful as an aid to the systems programmer in 


determining why SDOS will not boot or why it 
crashed; after à failure, the programmer may see 
the cause by looking bere if the error routine in 
SDOS did not print out the reason for failure. 
Locations $FC,$FD point to a jump; the jump 
"points" to the SYSCALL entry point into SDOS; the 
2 bytes preceeding the entry point contain a 
pointer to the base of the SDOS: entry points. 
This information allows a programmer. to find 


. SDOS: LASTERROR after a system. crash. 


SDOS: CONFIGURATION 


SDOS:CONFIGURATION is a 16 bit pointer to the I/O 
package configuration table (CNFIG:). This is 
really the only entry point to the I/O package, and 
is set by the I/O package: via an assembly like the. 
EE Iu 


ORG SDOS+SDOS : CONFIGURATION 
FDB CONFIGURATION 
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E ; ` ORG ns x 
|. .(see configuration table). 

. SDOS:SERIALNUMBER _ E = | 
s This is a 16 bit seriàl number assigned to this 


particular copy of SDOS. ` 


.SDOS: IOBLOCKPTR " x ee 
A Pointer to the SYSCALL block associated with the 
SYSCALL currently being. processed; set by SDOS for 
use by device drivers to get parameters from 
SYSCALL blocks. | 
' , SDOS: CLOCK ' : ^ ; | 

. A 24 bit unsigned integer counting 66HZ clock. 
ticks. This clock is zeroed at midnight. 


SDOS:DAY š ° : 

: l Day number in BCD ($01'- lst day of the month). 
Automatically updated at midnight. This byte must 
be set to zero at assembly time so that SDOS can 
detect that the time is not. set. | 


SDOS : MONTH : A. D 
Month number in BCD ($01 = JAN, $02 = FEB, etc.) 
Updated at end of month. February 29 is handled 
correctly on leap years. 


SDOS: YEAR | | | | 
Year number modulo 106.in BCD ($78 = 1978).  Bumped 
on transition of date to January 1. : ; l 


-SDOS : STACKSWITCHED . : 

l Eight bit counter used by interrupt routines to 
determine if a stack switch to the interrupt stack 
has occurred. -1 means "stacks not switched"; 
Switching stacks or taking an interrupt bumps this 
counter. If bumping the counter causes it to go to 
zero, then the current value of the stack register 
is saved in a TCB (task control block), and a new 
Stack pointer value is loaded (equal to the highest 
usable byte of the INTERRUPTSTACK). All interrupt 

, routines run using the interrupt stack, not a 

|, TASK's stack.. l P QE i 
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* |, .. INTERRUPT GOES HERE `. S "e 
ee ie SDOS+SDOS:STACKSWITCHED 
BNE UL UO po A éi v 
LDX CURRENTASK `“ 
STS- TOB:STACK,X. 0 
LDS ` SKINTERRUPTSTACK. 
L1 j EQU * e an B c 


Nested interrupts do not switch stacks again. On 
exit from an interrupt routine, SDOS:STACKSWITCHED 


must be decremented; if it. goes negative, a switch 


back to the task's stack is required (see section 


on INTERRUPTS). Sch x 


I/O Interrupt entry point. 6804's with only a 
single I/O interrupt vector. should aim it at... 
SDOS:IOINT. SDOS:IOINT adjusts SDOS:STACKSWITCHED, 
effects stack switching if required, and then 


_ transfers control with interrupts disabled to 


CNFG:IOINTPOLL, which is an I/O package routine to 
determine what device caused. the interrupt, and to 
go handle the interrupt. Once in the interrupt. 
routine, the routine may re-enable interrupts for a 
nestable priority-interrupt driven system. l 
INTERRUPTSTACK must be deep enough to handle all 
the pushdown storage required by the nested 
interrupt routines + 9 bytes for the task 
Scheduler. ` 


SDOS:RTI is the exit for an interrupt routine that 
has discovered nothing of interest happening. (from 
the point of view of a task waiting for that 
interrupt routine).  SDOS:RTI disables interrupts, 
adjusts SDOS:STACKSWITCHED by decrementing, and 
returns control to the previously nested interrupt 
routine or user task if no higher priority | 
interrupt routine has signalled an interesting 
event. If there are no more nested interrupts, and 
some interrupt routine has signalled "interesting 
event occurred", then the task scheduler is invoked 


and task switching may occur.. ` 


SDOS:RESCHEDULE __ ee 


SDOS:RESCHEDULE is the exit for an interrupt | BS 
routine that has discovered an event that may be of 
interest to a task. The particular event and any 
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associated data must be set up independently of 

this call (see WAIT routines); this. merely sets a- 
flag and passes control to SDOS:RTI. ` Eventually $ 
(when all of a nested burst. of interrupts have been 

processed), the scheduler will gain control and. : 
reschedule the tasks, including waking up one that 
might have been waiting for the event. or interest. 


SDOS: CLOCKTICKED - 
This routine SE control from the timer interrupt. 
routine, with the number of 1/6@th<second clock 
ticks since the previous call passed in the A 
register. SDOS:CLOCKTICKED updates the system 
clock and date as needed and causes the timeout 
task to run.  SDOS:CLOCKTICKED can be run with 
interrupts enabled or disabled, as. long as: no 
interrupt.routine reads the clock if ` 
SDOS:CLOCKTICKED runs interrupt enabled. If no 
clock device or regular source of interrupta is 
available, a psuedo-clock can be constructed by 
placing a dummy task on CNFG:TASKQUEUE whose only 
business in life is to be stuck in a permanent wait 
State, so that its wait routine can increment a 
counter to be used as a clock. SDOS : CLOCKTICKED 
exits to SDOS:RESCHEDULE when it is done. Calling 
this routine causes timeout blocks to get checked 
for "timed out". ` 


SDOS : CURRENTASK 
-SDOS:CURRENTASK is a. pointer to the TCB of the task 
most recently run (or considered by the scheduler). 
This is used only by stack-switching routines as 
described under INTERRUPT systems. 


SDOS: KILLPROOF 
This is a one Bite flag, which, if not zero, 
indicates that the application program is not to be 
"killed". . The flag is set and cleared by 
SYSCALL:KILLPROOF and SYSCALL:KILLENABLE ‘syscalls 
respectively. This flag is checked by- 

. SDOS: KILLUSERPROGRAM (not by the ^C recognition in 
the CONSOLE: driver) and by ^D (debug call) 
recognition. A ^D is to be ignores if this flag is 
set. I ; ! 


DOS: KILLUSERPROGRAM 
This. routine is called. By an 1/0 package: routine 
that recognizes an operator request to kill the 


Copyright (C) 1978 Software Dynamics 
GH -192- 


SDOS USER'S MANUAL 


úser program currently running. Normally, this is 
recognized Dy the CONSOLE: driver when the operator 
types two ^C ^C characters in succession. 
KILLUSERPROGRAM decides if the user program is 
killable by examining SDOS:KILLPROOF; if not, a 
return with carry set (error!) (ERRORRTS) is 
executed. Otherwise, the user. program: (logging, 
and the currently active DO file) is aborted 
(instantly, or via a time bomb, depénding on what 
the user is doing at the moment) and control 
returns via OKRTS (with carry reset). . If the user 
task is currently executing (or waiting) in a. 
device driver, then SDOS delays the "kill" action 
until the task has left the I/O driver and returned 
to execution in SDOS. Since execution of a driver ` 
operation will either complete or time-out in a 
- fixed period of time, this delaying action is safe. ` 
The user program eventually gets killed. The 
CONSOLE: driver has a special problem; there is no 
time-out on an input wait! This is solved by 
having the CONSOLE: driver perform a forced wake-up 
of the task when KILLUSERPROGRAM says "OKRTS" and 
the CONSOLE: driver detects that the task is in 
input wait mode (which it can do by making the task 
set an "I'm about to wait for input" flag). 


.SDOS: STARTIO 
This SU EOULIRE: is used only by task devel parts of 
the I/O drivers to cause a simulated interrupt to 

. the address specified by the X register.  SDOS 

disables interrupts, pushes a context block 
containing the return address, switches stacks to 
the interrupt stack, and goes to the address 
specified by X. This routine is used to start the 
operation of the interrupt portion of the driver, 
if the interrupt portion is not expecting another 
interrupt. 


SDOS: WAITCOND 
i This subroutine causes a task to wait for a 
a condition specified by a test subroutine whose 
b address is in (A,B,), with a parameter in X. The 
D task is put to sleep until the condition occurs; 
other tasks of lower priority then have an 
. opportunity to execute. When the condition has 
occurred, the task continues. execution at the 
return address. The test subroutine is called 
‘periodically by the scheduler; on entry to the test 
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“subroutine, X is equal to the original parameter ; 
(usually the address of something). - The subroutine 
must return a code in the A register. Zero means `` 


"not ready"; not- zero means task is ready. The. 
test subroutine ceases to be. called when it: signals 
the task has gone ready. When the task wakes, it 


will find the ready code returned by the test 


subroutine in its A register. The test. subroutine 


must not disabie interrupts (for long), nor may its 


execution take considerable time without slowing 
down the real-time response of SDOS RE 
Furthermore, the test subroutine is called using. 
the INTERRUPTSTACK, not the task's Stack. The 
generality of WAITCOND is hardly ever needed. 
Normally, SDOS:WAITEVENT is sufficient. On return 


. from WAITCOND, interrupts have been enabled. The 


conditional test subroutine must not push any bytes 
on the stack as the interrupt s may not have 


Space reserved for this. 


SDOS:WAITEVENT 


This subroutine causes a task to watt for: the byte 


pointed to by the X register to become non-zero. 


It works as a special case of SDOS: WAITCOND; 
essentially, the test subroutine is: 


LDAA B, x 
RTS 


where X contains a pointer to the desired Erte: 
The task continues execution at the return address 
with the A register set to the value of byte at the 
time that the scheduler, via the test: subroutine, I 
discovered the byte to be non-zero. This is 
particularly useful in synchronizing a task to an 
interrupt output buffer free counter (if the 


“counter is zero, the task automatically waits) or 


an interrupt input buffer counter. As an example: 
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E 
£ TASK LEVEL ROUTINE: (A) 
- CONTAINS CHARACTER TO OUTPUT 
LDX ` ` #OUTPUTFREECNT 
LDAB 0,X WAIT EVENT IS SLOW, 


GE ' " f SO THIS OPTIMIZES THE . 


BNE L1 
PSHA .  — bx | i | 
JSR SDOS4SDOS:WAITEVENT ` — X CONTAINS POINTER TO 
"a | | | ` COUNTER 
PULA MS 
Lis DX ` , OUTBUFPTR PUT CHARACTER INTO BUFFER ` 
Lr Pe SPAR Ø,X | : Ge 
DEC OQUTPUTFREECNT ` LET INTERRUPT ROUTINE KNOW 
E (NOW OUTPUTFREECNT <> SIZE OF 
mom A atu. af BUFFER) s PACTI S 
INX — > ...' BUMP BUFFER ADDRESS > 
STX .  OUTBUFPTR 


On return from SDOS: WAITEVENT, interrupts have been 
re-enabled. 


. .SDOS:ERROR | 
e SDOS:ERROR is the standard routine used by the user 
E se de i task to signal an error. A two byte error code is 

l placed in the line following the JSR to SDOS:ERROR. 
A JSR is required even though control is not 
returned. The error code is loaded into the X 
register; the carry is set; and the subroutine 
which signalled the error is aborted and control is 
passed to the return address specified by its 
caller. If the caller does not have a BCC or BCS 
instruction at its return address, then the caller 
is likewise aborted and control is passed to its 
| caller. This process continues until a BCC or BCS 
ou is found at a return address (see ERROR HANDLING). 
Suitable error codes, are defined in the 
SDOSIOPKDEFS.ASM file; these error numbers may be 
augmented as needed. This routine may not be used. 
by interrupt routines or by any non-user task. ` 
i | 
Example Use: 


TST. TTYEOPFLAG 


BEQ eee.  .B/ NOT EOF 
JSR SDOS+SDOS: ERROR ` 
FDB ERR: EOFHIT 
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EI ERRORSAVE e 
.SDOS: ERRORSAVE is a user task subroutine Pree is 
used to store the X register (presumably containing 
= an error number) for later use by SDOS:ERRORED. 
R pe SCH : ^" This is done if an error recovery routine will pass 
ks nM IE. - the error on after cleaning up. It does not hurt 
Sa ` to do an SDOS:ERRORSAVE even if SDOS:ERRORED is not 
later used. Note that if the error recovery i 
routine invokes subroutines which can error, the 
saved error code will be destroyed! If this 
"E ¿+ possibility can occur, the recovery routine will | 
c——À— have to save the error code somewhere else, and 
pom issue a SDOS: ERRORSAVE later before it does. an. 
|; SDOS: ERRORED. ; Ss 


stoe: ERRORED l : i E l | 
cc This. is used. ay: the user. task. .to ‘signal. that an. 
"error recovery routine is finished, and wishes to 
pass the error back to the caller.  SDOS: ERRORSAVE | 
must be called before SDOS:ERRORED is used. This 


entry point requires no peraneterme An example of. 


use is: 
- y | JSR WIDGET 
dee | BCS OOPS ` B/ ERROR: 
OOPS) JSR ' §DOS+SDOS: ERRORSAVE 
CPX #ERR:... 
BNE OOPSOOPS 
; «do recovery» `: 
OOPSOOPS JMP .  SDOS+SDOS: ERRORED 


: SDOS: CHECKRDLEN I I 
SDOS: CHECKRDLEN is a user task subroutine used to 
check that the reply buffer length of a SYSCALL 
block is at least as large as the two byte value 
coded inline following the call. This call is used 
as a convenience to I/O drivers. The SYSCALL block 
checked is that specified by SDOS:IOBLOCKPTR. An 
error (see SDOS:ERROR) is caused if the SYSCALL ` 
block is too short to have à reply buffer, or if 
the reply buffer. length is not at least as large as 
the inline value specified. If an error occurs, 
control does not return; if no error occurs, 
.SCBLK:RPLEN.in the SYSCALL block is set. to the 
specified inline value and control returns to the 
point following the inline value. The X register 
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is left pointing to the SYSCALL block. to make 


further processing convenient. 


Example: | 
JSR SDOS+SDOS:CHECKRDLEN  . 
FDB 5  :MUST HAVE >= 5 BYTES OR WE 


PR RETURN HERE IF OK 


..SDOS: CHECKWRLEN 
..9DOS: CHECKWRLEN is a user task ‘subroutine | to check 


Chat Che write butter length oft a SYSCALL block is 


at least as- Long as Che two byte value coded - inline E 


following the call. This call is used as a 


convenience. to the I/O drivers. The SYSCALL block 


checked is that specified by SDOS:IOBLOCKPTR. An  . 
“error is caused if the SYSCALL block is too short. 

to contain write buffer pointer and length, "Or if 
SCBLK:WRLEN specifies a value smaller than that 

given by the inline value. Otherwise, control 
returns to the point following the inline value.. 

The X register is left pointing to the SYSCALL 

block to make further processing convenient. 


Example: - 
JSR SDOS+SDOS:CHECKWRLEN ` ; 
FDB 2 MUST HAVE >= 2 BYTES OR WE 
f , ERROR 
* `. RETURN HERE IF OK 
LDX SCBLK:WRBUF,X I 
LDAA Q,X GET DATA BYTES 
LDAB l,X FROM WRITE BUFFER 
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. THE CONFIGURATION TABLÉ (CNFG:) 


This table tells SDOS the specific configuration (i. ec, 
hardware, device drivers, etc.) in which it is running. The 
builder of an I/O package must plant a pointer in Kë 

SDOS: CONFIGURATION to. this table. so that SDOS can find it. 


CNFG: DISKDCBS 
-CNFG: DISKDCBS is a pointer to a list of DISKINFO: 
tables. Each DISKINFO table describés a physical ` 
. disk drive and gives SDOS access to the sector 1/0 
. routines. needed to do disk 1/0. The first DISKINFO ` 
table. in the list usually specifies a device name ` 
2 Of U"D8:" and. is used initially as the default disk 
device when opening or creating. files. All disk .. 
p are mentioned. in- Eie list. | 


"CNFG: DEVICEDCBS is a STEE Co a list of non-di&k 
device control blocks. Each DCB specifies a device 
name and a driver entry point vector to be used . 
when. executing I/O SYSCALLs for. that device. All 
non-disk devices must appear in this list. The 
: first device named in the list is treated as. the 
CN ` Operator's console, and is normally named 
Ns 


CNFG: IOCBPTRS ` 
CNFG: IOCBPTRS points to a table of Tonteg to I/O 
control blocks. There is one IOCB for each. I/O 
channel defined. Most SDOS systems have eight user 
I/O channels. The IOCB's are used by SDOS. to keep 
track of open disk files, and to know which driver 
to call for non-disk devices. The number of IOCB's 
is selected at I/O package generation time. 
Immediately preceding the table of pointers must be 
a table of File Control Blocks. There must be one 
FCB for each IOCB, two for each disk drive, plus ` 
¡NMAGIC FCB's which are used by SDOS. Typical code . 
for the FCB! S, table of pointers, and IOCB's is: 


E | RMB p? | E FCB: SIZE* (NIOCHANNELS*2*NDRIVES* 


. er NMAGICFCBS) 
oe | RMB | ^1. IOCB:SIZE*NIOCHANNELS 
dt - CONFG:IOCBPTRS MUST POINT HERE 
- IOCBPTRS |^ RPT |. J NIOCHANNELS . 
| FDB ` x IOCBS+IOCB: SIZE*(*- 3OCBPTRS) /2" 
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CNFG: NIOCHANNELS 
f This byte contains the number of. 1/0 channels 
configured into this I/O package. ($ is s sido ros 


CNFG: DSKBUFFERPOOL : 
CNFG:DSKBUFFERPOOL points to the base of a disk 
Sector buffer pool. At SDOS boot time, SDOS 
dynamically allocates a set of sector buffers from 
this area. The size of the sector buffers is the 
maximum of the sector sizes used by all the disk 
drives in this configuration. Furthermore, all 
sector buffers are allocated on a power of two . 

. boundary corresponding to the size of the sector . 
buffers. Finally, one control block per sector 
buffer, describing the sector buffer is allocated 

- . from this region.  SDOS must be able to allocate at 
coo deast.two.control and sector buffer blocks from 
this region, or it will not boot; however, much 
better system performance is obtained if the number 
of sector buffers available from this pool is 
slightly larger than. the cluster size. Usually, 
the region Size is chosen to be whatever memory 
f space is left over after SDOS and the I/O package 
N are placed into the memory. anpigned to them. 


CNFG:DSKPOOLSIZE 
This 2 byte value tells SDOS how much space is 
available in CNFG:DSKBUFFERPOOL. 


, CNFG: ATTNCHECK 

! CNFG:ATTNCHECK contains a pointer to a routine that 
checks to see if an operator request for attention 
has occurred (typically, the console: input 
interrupt routines simply set a flag when the 
ESCAPE key is struck). The routine does an OKRTS 
if no request has occurred, otherwise, it calls 
SDOS:ERROR with ERR:ATTENTION, 


Typical code for the attention check routine might 
be: X . 


E 
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-ATTNCHECK `. EQU Wa 
Se ! LDAA ESCAPEHITCOUNT 
BNE ATTNCHECK1 
GA | OKRTS 
-ATTNCHECK1 |  EQU  . * | 
; de CODEC ^C ESCAPEHITCOUNT ` 
A H vi RESET ESCAPE HIT FLAG. 
| JSR  . §DOS+SDOS:ERROR - 
. FDB © ERR: ATTENTION. 
ME qM IN CONSOLE INPUT INTERRUPT ROUTINE 
| | CMPA ` , SESCAPE 
EE e -BNE aes 
a ING. CESCAPEHITCOUNT 
pe e 2 IMP... SDOS+SDOS:¿RTI. 
à Er Ae 


CNFG:DEBUGGER contains a pointer to the entry point 
of the local debugger program. A SYSCALL:DEBUG 
call causes SDOS to leave the return address of the 
SYSCALL on the stack and transfer control to the l 
address specified by this point. If CNFG:DEBUGGER 
contains a f, and a SYSCALL:DEBUG is executed, SDOS : 
will abort the user's program with ERR: NODEBUGGER. 


CNFG: DRIVERBASE 


This contains a pointer to the lowest address 
memory byte occupied by the drivers if the I/O 
package sits below SDOS in memory. Otherwise, it 
must point to SDOS-3. .A JMP to the SDOS entry 
point is planted by SDOS on a CHAIN or LOAD 
syscall; this address also constitutes a ceiling on 
` the DEES available to user programs. 


CNFG: INTSETUP 


CNFG: INTSETUP contains à pointer to a subroutine to 
set up the interrupt system operation. Normally, 
this routine initializes the interrupt hardware of 
the processor (i.e., sets up interrupt vectors, | 
etc.). It is called once by the initializing phase 
of SDOS: immediately after booting and then is never 
called. again. This routine does not enable 
interrupts! It is appropriate to place this 
routine in a buffer area used by a driver so that. 
Do penalty is paid for the space it occupies. 
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. CNFG: INTDISABLE 

= CNFG: INTDISABLE contains a 3 byte subroutine to 
disable interrupts.. For most 6800's, this consists 

merely of: BUE f 


NOP + deër. Bish ef ei SEN 
SEL a | 8 
RTS 


For more complicated interrupt systems, a JMP to an ` 

‘interrupt disable routine can be used, Note: 
..F;!J))à3£E G3 IN TDISABLE must. preserve the X register! A 
-ahd B. can be damaged... This routine should be as ` 

efast- -aS possible. ccc Lum d 


ONPG: : INTENABLE o | 
` CNFG: INTENABLE contains a 3 byte subroutine to 


Cémable interrupts. For most 6800" s, this consists `: 
merely of: 


CLI 
RTS 


| More complicated routines require a JMP to be 
iu placed here. The X register must be preserved; A 
in l and B can be damaged. This routine should be as 
fast as possible. ` l 


;  CNFG: INTRTI 
l This contains a 3 byte routine to re- -enable the 
` interrupt system based on the state of the I bit in 

CC register in the context block specified by the 
top of the stack, and then perform an RTI, Most 
6800 systems simply use an RTI instruction here. 
For more complex interrupt systems a JMP to a 
routine can be Preece here. f ; 


CNFG: INTERRUPTSTACK I 
CNFG:INTERRUPTSTACK is a pointer to the SE 

available byte of Che space reserved for Che 
interrupt stack. The interrupt stack must have 
space for an NMI context block, space for context 
blocks pushed’ by nested interrupts, space for bytes 
pushed by JSR and PSH~ instructions in nestable 
interrupt routines, plus 9 bytes (for a scheduler 

` context block plus 2 pushed bytes). 


CNFG:IOINTPOLL 
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CNFG:IOINTPOLL contains a pointer to the device 
poll routine which is used to determine which. 
device caused an interrupt. If the I/O. package is 
configured to transfer control to SDOS:IOINT when 
an IRQ occurs, then, after stacks have been ` ` 
switched, SDOS will JMP to CNFG:IOINTPOLL. If 
SDOS: IOINT is not used, then CNFG: IOINTPOLL is 
ignored. 


CNFG:TASKQUEUE ` 
This is a. pointer to a list of. 1/0 task TCBs. The 


user task TCB is added by SDOS to the end of this 


list at “initialization time. Each TCB points. to 
the next TCB, or points to 0 to signify end of. 
list. If (as is. usually the case) no special: I/0 
. tasks are needed, CNFG:TASKQUEUE must be zeroed. ` 
Task priority is determined by the order of this 


- may not be added to this list ‘dynamically. 


CNFG: TIMEOUTLIST 
CNFG:TIMEOUTLIST is a pointer to a list of timeout 
blocks (see TIMEOUT BLOCKS). Each timeout block ` 


points to the next timeout block or, to Ü to signify | 


~N | end of list. -SDOS counts the number of timeout 
| l blocks in this list at initialization time. 
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CONFIGURATION Table 


^. This table contains all the information required by SDOS to 


determine its particular configuration. In particular, the 


CONFIG table lists addresses of physical disk rivers, 
non-disk device drivers, ees etc. 


SDOS ` 
CONFIGPTR 


--»ICNFIG:DEVICEDCBS 
ICNFIG: DISKDCBS 
! a 
ICNFIG:DSKBUFFERPOOL 


.SDOS 


pr ER A gx i 
P ce ius esa Wash e e Vom c Rom Dee Rom Ia AE (ce a mab uS quq 6s u qi= ege RE 


e 5=—v $a fo ` fen de geng p= 


! - POINTER TO SPACE 
z FOR DISK. SECTOR 
d BUFFER 
ICNFIG:DSKPOOLSIZE 
! SIZE OF SPACE : 
L AVAILABLE FOR DISK 
i SECTOR BUFFERS - 
LETC. ' š 
! 
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TASK CONTROL BLOCKS (TCBs) 


| Each potential parallel execution of a program is called a 


"task". Tasks are represented inside SDOS by Task Control 
Blocks, which serve to give tasks an identity, and provide. 


. Storage for information critical to the revival of a task 
= when it is needed or ready to run. 


A. TCB- has the following format: 
* : . TCB (TASK CONTROL BLOCK). DISPLACEMENTS 


RS D 


-—— mcm d nan | s O pon er? 
DCH: LNK DO S RMB e 200 75v POINTER TO NEXT TCB IN QUEUE 
- TCB:STACK ` RMS 2 ` STACK POINTER FOR TASK ` 


* . ON TOP OF A STACK IS ALWAYS A CONTEXT BLOCK | 
TCB:COND _ RB .2. ,  TASK'S WAKE UP ROUTINE ` 


TCB:SCRATCHPAD RMB’ . 8 SPACE FOR TASK'S SCRATCHPAD 
f f (LOCATIONS 6-7) 


TCB:SIZE | EQU * SIZE OF TASK CONTROL BLOCK 
E | | 


 TCB:LNK is a pointer to the next TCB in the TCB list " 
specified by CNFG:TASKQUEUE. Zero means "end of list". Task ( 


priority is determined by the position of the task in the 
queue; highest priority being the task selected by ` 
CNFG:TASKQUEUE. ` 


TCB:STACK is a ree area in which the current value of a 


‘task's stack register. is stored when the task is EE 


or WAITing for an event, 


TCB:COND is the address of a sa susunan to test whether Or. 
not this task should be running. The SDOS task scheduler 


periodically calls the subroutine for a task to determine 


-.whether or not the task should be given some CPU time. This 


subroutine address is changed by SDOS:WAITEVENT or 
SDOS:WAITCOND, and is set to a special value (' executing' ) 


for a task which is in execution and needs more CPU time. 


TCB:PARAM is a 16 bit parameter. passed in the X register to 
the subroutine specified by TCB:COND when called by the. ` 


scheduler. Usually, this parameter is the address of an 


Ge event for which the task is waiting, and is a good way to 
determine what the task was doing if the system crashed. 


Actual use of the parameter is determined by the subroutine. 
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 TCB:SCRATCHPAD is an 8 byte area used to save page zero 


locations Ø to.7 when a task is interrupted or forced to- 
wait. Because the scheduler saves and restores these 
locations. every time a task context switch occurs, each task 


‘effectively owns its own copy of locations Ø to 7. This 
^ provides fast and convenient scratch storage for the task (a 


typical use for an I/O task is to place a DCB address in 


.. location 6; without this scratch space, no task could safely 


push the contents. of the X register onto the stack without 
disabling interrupts!!). This scratchpad also serves to 


.Shorten the effective lehgth (in. both time and space) of 
routines executed by a task. 


To add a task. to CESEN? some: special function, the following 


must be added to the I/O package: l 
pe ) A. Task Control. Block-for that task must be defined. cco) 


2.) The TCB must be linked into the CNFG:TASKQUEUE list. 
3.) A stack for the task to use must be defined, with an I 
initial context block set up to contain a start address for 


‘the task, and a condition code byte which enables interrupts. 


The stack must have enough space for a fake context block 


. (built by the scheduler), an interrupt context block, an NMI 


context block, plus some stack space needed by scheduler, 


^ (this amount is defined by MINSTACK in the SDOSIOPKDEFS.ASM 


file), plus whatever extra stack space is used by the task 
(return address, pushed data, etc.). ` 

4.) The stack pointer value in the TCB must be set in such a 
way that the initial context block will be used when the 
scheduler starts the task. E 


When SDOS is first started, the task is marked as 'in 
execution' and will execute as soon as all other tasks of 
higher,priority have entered a wait state. When the task 
Starts execution at the task start address specified in the 
initial context block, it should perform any dynamic | 
initialization of any tables it might need, and then wait for 
whatever wake up condition is appropriate. | ' i 


SDOS comes with two built in tasks: the User task; which 
actually executes the user program and Shows up at the task 
level of the I/O drivers, and the Timeout task, which is A 
triggered by SDOS:CLOCKTICKED and adjusts the.contents of the 
Timeout Blocks. I 


‘Copyright (C) 1978. Software Dynamics 
-205- f 


SDOS USER'S MANUAL ` 


Example: 
ORG ` CONFIGURATION+CNFG:TASKQUEUE 
FDB” SPECIALTASKTCB | 
phe cu . STACK SPACE FOR TASK. 
| RMB  MINSTACK+EXTRANEEDED-7 ^... 
FCB Ø . INITIAL CC--> | 
uL NC | ^ INTERRUPTS ENABLED ` 
RMB 4 ae ' FOR. GARBAGE A, B, AND 
' X. " D $ 
FDB . SPECIALIOTASKSTART | . ADDRESS OF . 
a =. ; f FIRST E 
.. INSTRUCTION 
TO BE | 
_ EXECUTED BY 
"T | | MSS TASK 
ke (5. ` TCB FOR SPECIALIOTASK 
SPECIALIOTASKTCB EQU * | 


FDB  nexttcb USUALLY NO MORE (ZERO) ` 
FDB | INITIALSTACK FOR SPECIAL. TASK 
RMB  TCB:SIZE-(*-SPECIALIOTASKTCB) 
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^. TIMEOUT BLOCKS 


Timeout blocks are used to time out interrupt- driven devices, 
and to perform various other timing functions (such as. 
unloading floppy disk heads After a predetermined period of 


TIMEOUT block 


"FUSE 
(16 BITS) 


. TIMEOUT ROUTINE 


Se Re fen uh fe Su ` geck e ` geen 
Sep Goer fat gav fe ç Qu» ° ` Sege, 


~ DCBPOINTER ` 


Each interrupt. routine should Be associated with one timeout ` 


- ‘block. 


At, each clock tick (every 6@th second), the next timeout list 
element is chosen (circularly). "FUSE", if non-zero, is 


decremented by the number of timeout blocks. on 


CNFG:TIMEOUTLIST, and if it goes zero or negative, the 


. timeout routine is called (in interrupt mode with the stack 


already switched; (A,B) will contain the DCBPOINTER selected 


by the timeout block). The timeout routine should initiate 


any desired activity, and then transfer control to SDOS:RTI 
or SDOS:RESCHEDULE. If FUSE is zero, the timeout routine . 


will not be called. 


On initiating an I/O operation (for which an interrupt is to 
be timed out), the time-out delay in ticks is stored (by the 
interrupt routine) into the FUSE field of its corresponding 

timeout-block. The interrupt routine is expected to zero the 
fuse field in its corresponding time-out block on receipt of- | 
its expected interrupt. The timeout routines are designed to! 
be timing-splinter proof; if the interrupt is properly | 


t 
"m 


acknowledged (by zeroing the time-out county: the timeout 
routine will not be called. EE ! KS 


Tt is intended that timeout list elements are placed into the 


time-out list statically at assembly time of. the I/O package. - 


Note: The actual timeout value used must bé equal to the 
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| . desired time-out (measured in 6@HZ clock ticks) plus the 
number of timeout blocks-in CNFG: TIMEOUTLIST. This value can 
be. computed at assembly time. . ee 


i 3 


= 

| 
| 

m $ 
! sz ! 
| | 
| i 
| i 
l 
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DEVICE CONTROL BLOCKS (DCBs) 


C Bach I/O device is made known to SDOS through a Device 


Control Block (DCB). .DCBs specify the device name, select a 


— driver, and hold miscellaneous data appropriate for the 
~ driver for that device. EE E 3 o : 


DCBs have two parts: a part defined by SDOS, and a SE 
-driver-specific part.” The form and content driver-specific 
part is completely determined by the device driver itself, f 
and so is of no concern here, except that the driver-specific 


portion immediately fol 


lows the SDOS-specific portion in a 


=. The SDOS-specific portion of “a DCB has the following format: 


ok DEVICE CONTROL BLOCK DISPLACEMENTS ` 
ORG g ` a ` 
 DCB:iDONEFLAG ^ RMB l --> DEVICE IS BUSY; <>0 --> 


DEVICE IS DONE 
IF DCB IS DONE, CONTAINS 


DCB:LASTERROR RMB. 2 
| ERROR STATUS (Ø = NONE ) 
DCB:NAME ` . RMB 2 POINTER TO DEVICE NAME STRING 
| | TERMINATED BY ZERO BYTE 
DCB:NEXTDCB ` ` RMB 2 POINTER TO NEXT DCB IN LIST 
| z OR ZERO wee TE 
DCB:DRIVER ` RMB 2 POINTER TO DRIVER ENTRY POINT 
| LIST | 


DCB:SIZE ` ` EQU: * DEVICE SPECIFIC DATA EXTENDS 
| DCB FROM HERE 


DCB:DONEFLAG is used by an interrupt routine to signal that 
an operation started on the device has completed; @ = busy, 
<> B means completed. Whether or not this flag is used is up 

to the I/O driver; SDOS does not use it directly. f 


DCB:LASTERROR was intended to hold device interrupt operation 


. completion status. Many drivers place Ø here to mean 


"completed ok", or place an ERR:something code to mean 


~ "device operation failed because of ....". Typical I/O 
driver code using DCB:DONEFLAG and DCB:LASTERROR is: 
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LDX DCBPOINTER WHICH POINTS TO DESIRED DCB 
LDX DCB:DRIVER,X FIND DRIVER VECTOR FOR DEVICE 
LDX ^ - DRIVER:STARTIO,X l WHERE TO TRIGGER ` - 
U ie S ur ur : INTERRUPT . 
JSR '"SDOS*SDOS:STARTIO TRIGGER FAKE 1/0 
l d E INTERRUPT 
LDX . DCBPOINTER WAIT FOR "DONE. 
JSR. SDOS+SDOS: WAITEVENT l 
LDX DCBPOINTER "GET COMPLETION STATUS. 
LDX DCB: LASTERROR,X ` ; 
CBEO ` — Ll ` BZ NO ERROR i 
SSR. .. SDOS+SDOS: ERRORSAVE. SAVE ERROR CODE. 
- JMP  SDOS*SDOS: ERRORED . .AND GO COMPLAIN! 
OKRTS : I/O COMPLETED 


(CLC 


DCB:NAME points to an ASCII 
‘this specific device, such a 
name must be legal, and all 
The name must be terminated 
is used as a template agains 
filenames are compared in de 
An example is: 


FCC | "CONSOLE:" 
FCB ø 


DCB:NEXTDCB is a pointer to 

or zero. SDOS currently has 
devices, and one for disk de 
treated somewhat differently 


DCB:DRIVER is a pointer to a 
device driver for.a device. 
the same driver. See DRIVER 


DCB:SIZE is the displacement 
“Per Fie data may, begin. 


Serrin (C) 19 


RTS) 


text string giving the name of 

s "LPT:", "DØ:", etc. 
letters in it must be uppercase. 
by a zero byte. This device name 
t which user-program specified 
termining which driver to use. 


the next DCB in a chain of DCBs, 
two DCB chains: one for non-disk 

vices.  DCBs on one chain are 
than DCBs on the other. 


vector of entry points to the 


Note that several DCBs may share 


entry points. 


into a DCB where device/driver 
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DRIVER ENTRY POINTS 


A Device driver is a routine which effects 1/0 operations on 


.a.device. Each device driver has several entry points. Each ` 


of these entry points has a specific 1/O function associated 


-with it. The entry points are located via a vector of. 
. addresses pointed to by the DCB for that device. SDOS 


supports two different device types: disk devices, and 


“non-disk devices. The form and meaning of the entry points 
- depends on what kind of device a driver is supposed to 


operate: 


Control is passed. to: a r Entry point when a user program 
“issues a SYSCALL to perform an operation on a device. handled 
by that driver. The driver is executed by the user task; the ` 


code in the driver must collect whatever parameters it needs 


from. the- SYSCALL-block;. set up the required 1/0; initiate Che o=. 
1/0 (by triggering the interrupt routines if necessary); and 
“wait for I/O completed if needed. Since the driver is ` 


executed as a task-level routine, it may perform WAITs, etc. 
EXIT via OKRTS if the operation succeeded, or via 
SDOS:ERRORED if some I/O error occurs while processing the 
SYSCALL (see error handling). 


-SDOS conveniently places the address of the DCB in location 6. 


(DCBPOINTER) for the driver's use. 


For non-disk device drivers, the SYSCALL block address may be 
found in SDOS:IOBLOCKPTR. The driver should check for the 
presence of read and write buffers in each SYSCALL before 
using them by calling SDOS:CHECKRDLEN and/or SDOS:CHECKWRLEN. 


Non-disk device drivers (i.e., those located via DCBs in the 


CNFG:DEVICEDCBS chain) have a driver enia y point table as 
O K f 
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.. DRIVER:DELETE . RMB. `` 
 . DRIVER:CONTROL RMB 
22. DRIVER: STATUS. RMB... 
| DRIVER: RESET... RMB. 
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xv ^ DEVICE DRIVER ROUTINE ENTRY POINTS ` 


* 

_ ORG | . 
DRIVER:OPEN RMB 2 OPEN FILE 
DRIVER:CLOSE | RMB 2 CLOSE FILE 
DRIVER:READA ` RMB. 2 READ ASCII ` 

 DRIVER:WRITEA ` RMB E^ "WRITE ASCII: 
DRIVER:READB  . RMB 22 READ BINARY 
DRIVER:WRITEB . . RMB 2 WRITE BINARY 


DRIVER:CREATE RMB 
DRIVER:RENAME . .RMB 


CREATE FILE 
 RENAME FILE 
DELETE FILE... SE 
DO. CONTROL OPERATION T» 
READ DEVICE (DRIVER) STATUS . 
. RESET DRIVER (ON. BOOT) l 
INTERRUPT ROUTINE STARTUP- 


DRIVER:STARTIO RMB... | 
. 2 |, POWER FAIL RESTART .— 


DRIVER: PFRESTART 


GU N NRIN INO IO N 


` = 
SE 


These entry points are used to execute a SYSCALL; their 


functional definition is very close to the SYSCALLs after 
which they are named. ; 


"The: I/O channel in the SYSCALL block (SCBLK:PARAMS byte) is 


meaningless from the point of view of the driver; it is used 
by SDOS only to determine which driver to call. : 


DRIVER:OPEN is passed control when a user program opens a 
file prefixed by a device name specified in a DCB which 
selects the driver. : The driver is expected to perform 
whatever actions are necessary to "open" the device for input 
or update. All devices must be OPENable (so that SC:GETTYP 
can be used to read the device type without knowing the type 


of device). 


The driver may use the filename portion of the device name to. 
further select a "file" (port, or whatever) under that name. 


If it does so, it must modify the reply buffer in accordance 
. with the SYSCALL:OPEN specifications. The device name has 


been parsed from the input string already, RPLEN is zeroed, 


-and the pointer advanced past the device Danes DEEDES. control 


is passed to OPEN. 


" DRIVER: CLOSE is used to "close" a Moe and usually causes 
`. the driver to flush its buffers. The SE block contains 
j nothing of interest to the driver. 


“DRIVER: READA is used to effect a READ ASCII. from the device. 
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The driver must implement the operation given by the. 


- SYSCALL:READA specification, including adjusting RDLEN in the 
SYSCALL block. ; . l . 


 DRIVER:WRITEA is used to effect a WRITE ASCII SYSCALL to the 
‘device. The driver must implement the operation.given by the 
.SYSCALL:WRITEA specification. td ` 


DRIVER:READB is used to effect a READ BINARY from the device. 


‘The driver must implement the operation given by the 


` SYSCALL:READB specification, including adjusting RDLEN in the . | 
"BYSCALL Block; — 0907 U cc Dr E 


/ DRIVER:WRITEB is used to effect a WRITE BINARY SYSCALL to the 
“device. The driver must implement the operation given by the - 


SYSCALL:WRITEB specification. or 


DRIVER:CREATE is passed control when the user executes a `, - 


SYSCALL:CREATE with a filename that selects the device. The 
driver is expected to perform any required operations to 
"CREATE" the device output stream. This operation is illegal 
if the device is input-only. The part of the filename . 
string, not including the device name prefix, is passed to 
the driver for its inspection, if needed (see DRIVER:OPEN). 
RPLEN in the SYSCALL block must be updated if the driver uses 


.part of the filename. 


DRIVER: RENAME is given control when a RENAME syscall is 
executed on this device. For virtually all non-disk drivers, 
this operation is illegal. If not illegal, the driver should 


` perform a RENAME in accordance to the SYSCALL:RENAME 


specification; RPLEN in the SYSCALL block must be updated. 


DRIVER:DELETE is given control when a delete operation is 
directed to the device. For virtually all non-disk devices, 
this operation is illegal. If not illegal, the driver should 
perform a DELETE in accordance to the SYSCALL: DELETE f 
specification; RPLEN in the SYSCALL block must be updated. 


DRIVER:CONTROL is used to effect a control operation on the 


device. On entry to the driver, the A register contains the. 


control sub-code (i.e., the contents of the SCBLK:PARAMS+1 
byte in the SYSCALL block). The driver must determine which 
control operation is desired (usually via a sequence of 


‘compare and branches) and implement the desired operation. 


Control operations not recognized by the device must cause an 
error. Each driver should implement the standard control 
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| operations of CC: ¿POSITION and CC: DUMPBUFFERS. . 


CR DRIVER: STATUS is used Co fesd device status. 


.Somewhere in the device DCB. 


driver must always be. able to 


“buffers, 
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‘Unique 
device-specific control operations may also be implemented. 
Data may be passed to the driver via the WREUF in the Ge 


EE 


On nte: 
register contains the status sub-code (the contents of. 
SCBLK:PARAMS+1). . The driver must determine which status 


the A. 


operation is desired, return the appropriate status in the 
- RDBUF specified by the SYSCALL block, and adjust RPLEN as 


needed. Usually, the desired status can be copied from 
An error must be signalled if | 
call is requested. A device 


return its type (SC:GETTYP).--- 


an unrecognized device status 


DRIVER:RESET is called at SDOS boot time, 
disabled, 


with interrupts 
to allow the driver to reset the device, initialize | 
etc. - 


except it must not enable interrupts. Return is made via 


- OKRTS unless an error in device initialization is detected. 


DRIVER:STARTIO points to. the interrupt routine start 1/0 
entry points, and is used only by the driver itself to 
perform SDOS:STARTIOs if needed. Many drivers ignore this 


"entry point" and use addresses wired into the driver: 


routine. 


DRIVER: PFRESTART is a pipe dream and is not BE used. 
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| DISK DEVICE (SECTOR 1/0) DRIVERS » 


Disk device drivers are treated Ee by SDOS, since SDOS 
includes virtually everything necessary to do file management 


- except the actual sector I/O routines (actually, SDOS 


T ad has a "non-disk". driver vector for all "file 
devices", and another for "disk devices", which has the same 
form and. use as the driver vectors descr ibed By non-disk 
device. drivers). 


. To add a new disk (controller) to the list of disk devices 
* "usuable by SDOS, only disk sector I/O routines need be coded, 


| and made known to SDOS via a new DCB added to the 


 CNFG: DISKDCBs chain. 
“The only operations reduircd of a disk (sector 1/0) riep iñ 


“read/write complete" , and: miscellaneous control and Status 
operations. Like non- -disk device drivers, when a disk driver 
entry point gets control, DCBPOINTER contains the address of 
the DCB for the selected disk. The DCB for a disk sector I/O 
driver has 3 parts: the SDOS standard part (see DCBs), à 
DSKINFO: part, and a disk-specific part. The DSKINFO: part. 
contains data manipulated by SDOS to keep track of each disk 
unit. The disk driver must not damage (store into) any part 
of the DSKINFO: portion of the DCB tables. 


A disk driver has an entry point vector of ERE following 
form: 


woe DISK SECTOR 1/0. DRIVER ROUTINE ENTRY POINTS 


CONTROL OPERATION 


» - ORG g | 

DRIVER:DISKRESET RMB 2 RESET THIS DISK 
| DRIVER ` 
DRIVER:DISKREAD RMB 2 INITIATE A DISK READ 
DRIVER:DISKWRITE RMB a2 | INITIATE A DISK WRITE 
DRIVER: DISKWAIT RMB 2 | WAIT FOR DISK I/O 
o COMPLETE 

DRIVER:DISKSTATUS RMB 2 READ DISK-SPECIFIC 
. - | | STATUS 

rg DISKCONTROL ` RMB 2 |. PERFORM DISK- -SPECIFIC ` 


DRIVER: DISKRESET 
e - DRIVER:DISKRESET is used at. SDOS boot time to reset. 
the disk device represented by the DCB selected by 

DCBPOINTER. Since it is only used once per 
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the I/O.package.is "start a read", "start a write", "wait for 
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"5 drive, the reset code may. be płaced in the 
disk buffer pool (see CNFG: DSKBUFRERPOOL). 


I DRIVER: DISKREAD 


DRIVER: DISKREAD is used to. initiate a disk read ` 
operation oh a disk. DISKREAD does not wait for 


- sector 1/0 to complete. The LSN of the sector to 


be read and the target memory address are given in 
the Sector Descriptor Block selected by the pointer 
DSKINFO:SECTORDB in the DCB for that disk. 


Typically, the task level part of the driver will 


MEME 


check the. LSN) for legality (by comparing it to 


. .DSKINFO:NLSN), and then tear the LSN apart into ite, ` 
. component cylinder, track, and sector addresses, | 


performing mapping as specified by 


-DSKINFO:MAPALGORITHM (note that LSN 9 must map to ./ 
physical” Sector 9, track 0, cylinder 0). This data — - 


would be placed in the DCB for the particular drive 
in space allocated to the DCB beyond DSKINFO: SIZE, 


and passed to the interrupt part of the driver via 


a STARTIO interrupt. Once the I/O is started, the 


driver may return control to SDOS via an OKRTS. 


The interrupt routine for the driver usually 
handles multiple retries and time- -outs as SDOS does 


not. 


DRIVER: DISKWRITE 


DRIVER:DISKWRITE is used to initiate a disk write 
to the selected disk. DSKINFO:SECTORDB points to a 
Sector Descriptor Block which specifies the LSN and 
source memory address of the transfer. Other than 
writing, DRIVER:DISKWRITE works identically to 
DRIVER:DISKREAD. For floppy disks, a verify 
read-back after write is recommended to increase 
reliability. e 


DRIVER: DISKWAIT 


| DRIVER: DISKWAIT is aged to wait for a disk transfer 
(started by DRIVER: DISKREAD or DRIVER: DISKWRITE) to: 
complete. The driver returns only after completion 
of the 1/0. Usually, the driver causes the user 
task to wait by doing an SDOS:WAITEVENT On . -: 
DCB:DONEFLAG (presuming an interrupt that completes 
the transfer sets the DCB: DONEFLAG). Exit via 
OKRTS unless a transfer error has occurred; 
otherwise, exit via SDOS:ERRORED after giving the 


| 
| | 
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“error code to SDOS:ERRORSAVE. SDOS will never call ` 
DISKWAIT without first calling DISKREAD or 
DISKWRITE. 


` DRIVER: DISKSTATUS 
T . DRIVER: DISKSTATUS is used to read. status from the 
disk driver. Only disk- -specific status is read 
this way; SDOS intercepts and performs the. status 
calls. SC: GETPOS, SC:GETCOL, SC:GETEOF, 
SC:GETFILESIZE, SC: GETTYPE, and SC:GETPARAMS. for 
disk device. All other status requests are passed 
ii O a driver, with the A register containing the 
: contents of the SCBLK:PARAMS+1 byte of the SYSCALL. 
“The driver must check the validity of the status” 
request. and. complain if an unknown status type is 
requested. The driver must adjust RDBUF and RPLEN 


"must not damage the SECTORDB block. Most disk 
drivers do not have any special status to be read 
"back, and therefore simply cause an Illegal Device 
Operation error when this entry point is called. 


DRIVER:DISKCONTROL 
: DRIVER:DISKCONTROL is used to effect non-standard 
CN control operations on a disk drive.  SDOS 
BEEN intercepts and performs CC:POSITION, 
CC:DUMPBUFFERS, CC:UNLOCKDISK and ` 
CC:SETMAPALGORITHM control operations directed to a 
disk device. The operation CC:DISMOUNTDISK is 
intercepted and executed by SDOS, but it is also 
`. handed to the driver so that it may eject the. disk, 
write out track buffers, or do any really final 
operations needed to let go of a disk. The driver 
is entered with the A register containing the 
contents of the SCBLK:PARAMS+1 byte of the SYSCALL.. 
The driver must check for control operations legal 
for this disk driver. Data for the control 
operation can be obtained from the SYSCALL block. 
The driver must complain about illegal control 
operations... 


A standard "special" control operation commonly 
implemented for disk drivers is CC: FORMATDISK. 
- This operation switches the disk write driver into 
Css. Le a "blind-write" mode, which is useful when writing 
t tie wt . all over an unformatted disk.  "Blind-write" mode 
vem um p TES. : is exited when a CC:DISMOUNT control operation is 
executed on the same drive. 
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- DCBs, Driver Vectors, and Drivers 


: -Device List DCB © DCB ` Disk List  ^DCB ` 
q-2---- > 1! E i ! NEEN p 
Qo------» | -2--2--2----» .... 00] ----- ---> 
------2-------- (3 (d ! -—-------- 1 
! Ir ——————— 1 ------- bo 1 ------- 
V GE? "udo VETE 1 1 oV ! Kach 
A d DE 1 1 1 M “A ! ! 
I FOC AP 1 ! 1 ` 1 UI T Disk i 1 1 `! 
Pee E da pd ! Name ! ! wp 
Ub vis E pics e dat bd BNET 
um M m 27 ar ao 
Ee 1 Í oa 
: 1c m 
DRIVERVECTOR 1 y 
1 | «------------- ! 1 
po —————————————- ; I l 
! ! l! Driver Code ! 
Lo o ! l 
^ ! ! | l-> T OPEN ! ! 
qo o ------- bs. age ! ! 
! 1 1 d-—-5 1 WRITEA ! ! 
! ! ! ! 
oem > | CLOSE ! ! 
IM sm ! ! 
ey 
a! 
OS Se cce Skee AA ae eee LLL ee ! 
! 
! — DRIVERVECTOR DISK DRIVER 
1 A 
1---» 1 N 1 WE 
| ` ------------------------ > 1 DISK RESET ! 
! ! 1 AN | ! 
bo eee enn ee > | DISK READ ! 
, ! a ! | ! 
po ————— == ---» 1 DISK WRITE ! 
! «d p^ve | ! 
- ! A—————————-l--—————---»5 | T 
! A M ! ! 


| 
I 
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| DSKINFO: Table 

The DSKINFO: ‘table is actus ue a part of sach and. every disk 
DCB, and is used to hold sundry information about a. disk. 
drive unit. : 


ee The form ‘of the DSKINFO: pae of the DCB. is as “follows: | 


Cak DISKINFO TABLE DISPLACEMENTS 
Ki 
ORG DCB:SIZE | | a ES 
DSKINFO:NBPS RMB _ NUMBER OF BYTES PER SECTOR ... 


PAEPAE SE A cement 


- i 

“DSKINFO:NSPT RMB 2 . NUMBER OF SECTORS PER TRACK 
.DSKINFO:NTPC.....RMB......2 _ .. NUMBER OF TRACKS PER CYLINDER. 
, DSKINFO: NCL" ORMB 2 NUMBER OF CYLINDERS PER DRIVE 


x. I THE FOLLOWING ARE FILLED FROM THE BOOT SECTOR 


+ DSKINFO:MINALLOC RMB LCN:SIZE - ALLOCATION 
a | Ge | | | MINIMUM FOR 
| NEW FILES 
DSKINFO:MIDALLOC RMB ` LCN:SIZE : ALLOCATION 
| | MIN FOR FILE 
i EXTENSION 
aS '^. DSKINFO:MAPALGORITHM RMB 2 . CODE TO SELECT | 
AI | | | LOGICAL TO PHYSICAL 
oy aes | SECTOR MAP ALGORITHM 
BOOT:PARAMSIZE  EQU *-DSKINFO:NSPC SYSTEM DEPENDENT `` 
PARAMETERS IN BOOT | 
TN | BLOCK 
* END OF BOOT SECTOR DISK INFO | 
* 
DSKINFO:LOG2NBPS —. RMB pns LOG BASE 2 OF 
| ER BOT DSKINFO:NBPS ` ` 
DSKINFO:NBPSMl RMB 2 ' = NBPS-1 FOR USE AS MASK 
a RAE SE | (QUICK "MOD NBPS") | 
. DSKINFO:NLSN | RMB  LSN:S12E NUMBER OF. LSNS FOR 
E | ; THIS DISK = 
TENES | NSPT*NTPC*NCYL 
DSKINFO:NLCN ` RMB -LCN: SIZE. NUMBER OF LCNS FOR 
P9 ae ju owe eT l THIS DISK = NLSN/NSPC 
-c DSKINFO:NBPC. ` RMB 2 NUMBER OF BYTES PER CLUSTER 
+ —DSKINFO:RANDMAP RMB ` © LCN:SIZE ^ "RANDOM" LCN TO _ ` 
QW ae TANE ET | DISTRIBUTE NEW FILES 
| ` DSKINFO:MAPLSN RMB LSN:SIZE LSN OF 1ST SECTOR IN 
Ee de | DISK 


` DSKINFO:DIRFCB RMB 2 POINTER TO FCB FOR SDIRECTORY 
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FILE. 


~ DSKINFO:MAPFCB RMB = 2 | POINTER TO FCB FOR  $DISKMAP 
KE FILE 
DSKINFO:SECTORDB | . RMB Ser? POINTER TO RDSI 
| Eee ys . CONTAINING LSN, 
Mud uos Euh ean olea beet . ADDRESS PARAMETERS 
;DSKINFO:BADLSN RMB ` 2913 LSN OF LAST SECTOR THAT 


; "E "Ea COULDN'T READ/WRITE/SEEK 
DSKINFO:SIZE EQU  .* i L l : 


DSKINFO: NBPS °  - | h 
—DSKINFO:NBPS.is the number of bytes per sector `. 
defined for. this EE and is fixed a assembly - 


E Zeus - 5 t ime SÉ 


` DSKINFO:NSPT 


DSKINFO:NSPT is the number. of sectors. per: track. 
"defined for this drive, and is fixed at assembly 
time.. e WW š 


| DSKINFO: NTPC 


DSKINFO:NTPC is the number of tracks per Agi nae 
defined. for this drive, and is fixed at assembly 
time. : l 


 DSKINFO; :NCYL 


DSKINFO:NCYL is the number of eviindere defined for 
this drive, and is fixed at assembly time. I 


DSKINFO:SECTORDB . E 
DSKINFO:SECTORDB contains a pointer to a Sector 
Descriptor Block when DRIVER:DISKREAD or. 
DRIVER:DISKWRITE is. called. 


DSKINFO:NBPS, :NSPT, :NTPC and :NCYL are the only values 


. assembled into the DCB for a drive. All the other DSKINFO: 


table entries are filled in by SDOS at initialization (i.e., 
before DRIVER: DISKRESET is called) or when a disk is first 
mounted. 


"AIL other entries in the DSKINFO: table need not concern the 


"^ Systems programmer: with the exception. that PES must. be ` 
ai toceted in the DCB for those entries. . 
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_ RESIDENT DISK SECTOR INFO (RDSI) TABLES ` 


SDOS automatically manages a set at physical disk sector 
buffers for the purpose of improving system throughput by 


eliminating unnecessary reads. and Bag owing automatic 


pead: she x 


These disk buffers are BE to bé. on Ge which 


are a muitepie of NBPS (for historical hardware reasons). 


A set of tables called RDSIs are used to keep track of these 
disk buffers and their status. There is one RIEL Rer ALRK ia 


buffer. Each RDSI contains: Bag | | 
erre RESIDENT DISK SECTOR INFORMATION BLOCK ‘DISPLACEMENTS: Se 


-* 

on d ORG. o ; | 

wi, RDSI:DISKINEO.... RMB. "Ar POINTER TO DISKINFO TABLE- FOR ` 

Be A 7 THIS DRIVE 
RDSI:LSN RMB  LSN:SIZE. LOGICAL SECTOR NUMBER 
e ) SC OF SECTOR 
RDSI:SECTORBASE RMB 2 POINTER TO ACTUAL SECTOR 
| CONTENTS 
"RDSI:FLINK RMB ` 2 FORWARD LINK IN LRU CHAIN 
RDSI:BLINK RMB 2 BACKWARD LINK IN LRU CHAIN 
RDSI:MODIFIED RMB 1 "THIS SECTOR MODIFIED" FLAG 
RDSI:STATE | RMB 1 STATE OF RDSI 
RDSI:SIZE EQU * 
A l | 
* RDSI STATE DEFINITIONS 
* 
RDSISTATE: IDLE. EQU Ø SECTOR TRANSFER IS COMPLETE | 
RDSISTATE: READING ` EQU 1 . SECTOR IS BEING READ 
| l l INTO MEMORY | 

RDSISTATE:WRITING ` EQU 2 SECTOR IS BEING 


WRITTEN FROM MEMORY 


. The DRIVE and LSN are used to keep track of the sector 


currently in the specified buffer. MODIFIED indicates 
whether the buffer contents have changed, and, therefore, 


.Whether the disk sector must be written back to the disk. 
M j i i 


“The Links are used to queue the RSDIs in a more or less Least 
E Recently Used fashion. Each time a new disk sector is read 
in from the disk, its, RDSI is placed at the top of the Least 


Recently Read queue. When a new sector buffer needs 


allocation, the RDSI at the bottom of the list is grabbed Geer 
used. The only variation to this scheme is the following: | 
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1.) A sector just we eee to the disk is placed at the bottom 


of the list. 
2.) A sector whose contents have been processed is placed at 


the bottom of the list. 


These two heuristics are intended to dump sectors whose 


r. useful life has been exceeded: 
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“SECTOR asi s BEGCRE Susu 


Sector Descriptor Blocks are passed. to a Disk Sector. Driver. 
(via DSKINFO:SECTORDB) and tell the driver Which” sector. to 


s. read/write and to what. memory address. 


^ Thé form of a Sector: Descriptor Block is as follows: 


R GH SECTOR DESCRIPTOR BLOCK DISPLACEMENTS e Sp 
k I SE z 
SS f |. ORG 0 | de ) 
_SECTORDB:DISKINFO.....;., RMB... 2 2. POINTER TO DCB POR 
mt rud pae cile l DRIVE CONTAINING 
- "SECTORDB:LSN. | ^ ^ .. RMB LSN:SIZE HOLDER LOGICAL 
xr d NES A E | SECTOR: NUMBER 
| ES ee | us .. OF SECTOR ` ` 
—"SECTORDB:ADDRESS ^" RMB ^ 2 ` ` MEMORY ADDRESS FOR 


- SECTOR 


SECTORDB:DISKINFO is a pointer to the DCB and is redundant 
from the point of view of the driver.  SECTORDB:LSN is 24 


` bits of Logical Sector Number.  SECTORDB:ADDRESS is the 
. target read address. 
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l 1/0 CHANNEL BLOCKS (IOCBs) | 


IOCBs are used to keep track of which I/O channels are open, 
eM to which driver the I/O channel is open, and to hold any 
es ie “channel-dependent data the driver may choose to store in it. 
cata Currently, only SDOS- proper modifies the contents of the 
M IOCBs; most of the IOCB area is used by. the disk file driver 
SE in SDOS to keep. track of open disk files... f 


The 1/0 T TA programmer need not concern himself with the 
contents of the IOCBs; he needs merely to reserve das 
X MM EE space, in the 1/0 package (see CNFG: TUGBE TR): I 


“TOCB =" 1/0 Channel. Blocks 


E 1OCB DEFINITIONS 


UC UNE a ORG Pon TN S w ee 
IOCB: DCB RMB | 2 POINTER. TO DEVICE CONTROL 
a A BLOCK i 
IOCB:CURLŠN : RMB  LSN:SIZE LOGICAL SECTOR $ or 
: l CURBYTE ! 
 QO0CB:BUFFERP ` RMB 2 ADDRESS OF 1ST BYTE TO 
TRANSFER 
ak .  IOCB:FCB RMB 2 POINTER TO FILE CONTROL BLOCK" 
IOCB: DRIVER RMB 276 POINTER TO DRIVER VECTOR FOR 
T AN l DEVICE ` à 
IOCB:EOFFLAG RMB l END OF FILE HIT FLAG 
IOCB:COLCNT RMB H COLUMN COUNTER 
IOCB:CURBYTE RMB 4 VIRTUAL BYTE # TO READ/WRITE 
| ' FROM/TO NEXT 
LOCB:LOCATEDF RMB io g --> NEED TO DO A 
l ; LOCATECURBYTE 
* l --> LOCATECURBYTE DONE 
- IOCB:DRDSI RMB 2 POINTER TO DATA RESIDENT DISK 
B E SECTOR INFO ` 
IOCB:NEXTBYTE RMB 2 . POINTER TO NEXT BYTE OF DISK 
Y SECTOR 
IOCB:BYTECOUNT RMB ` 2 ` NUMBER OF BYTES LEFT TO 
l l PROCESS IN SECTOR ` 
=. - IOCB:CURLCN ` RMB © LCN:SIZE . CURRENT LOGICAL ` 
X CLUSTER NUMBER BEING 
Mu ecu | S S ROCBBSED 
c CEOCB:DRSN - RMB . 1 RELATIVE DATA SECTOR NUMBER 
uc AO e e e Ee a WITHIN CLUSTER ` f 
i -YOCB:RDCN  . RMB ` LCN:SIZE | RELATIVE DATA CLUSTER 
| MN EIE f | DATA ` 
* CLUSTERS WITHIN THE FILE (-HEADER 
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CLUSTER) 


IOCB:RBN . RMB ` NE RELATIVE BYTE # WITHIN A 

| ; Se l . CLUSTER .- 

IOCB:HRDSI ` RMB. SA watt POINTER. TO RDSI FOR CURRENT 
WE peer Fo d l AS ue HEADER BLOCK ; 

qOCB:HRSN. | RMB cv az RELATIVE SECTOR NUMBER OF 

dues m cs SE HEADER SECTOR 

. IOCB:SIZE . EQU | ,* 

IOCB:DISKWRITELOCKED EQU ` IOCB:LOCATEDF l --» DISK .: 


"DEVICE" IS 
WRITE LOCKED 


^ I0CBs are I/O control^blocks, and contain all the information 
. required by SDOS. to access a EE E ‘driver or a disk: 
file. ; 


“TR ERS case OF A E driver, Xe 3068 contine HIS 
the driver address, an 'EOF hit' flag, and a column counter. 
The driver is expected to allocate and maintain its own I/O 
buffers and/or any other control information required. 


For disk files, the IOCBs contain information describing 
current logical byte position within the file, the Header 
Cluster Number of the file, Current cluster number (being 
accessed), etc. 


There is one IOCB for each i/o channel defined by a 
particular version of SDOS. This number of channels is 
defined in the configuration table. 


A special IOCB is invisibly allocated permanently to SDOS tó 
deal with system files like the directory and the disk map. 


This special IOCB is used as temporary storage or as an IOCB, 


depending on the SDOS routine using it. 
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` IOCBTBL ` | Loo su u SYSrOCB ` 
! | (d ! ! l 
Lo ewe mee ebe eee SE cu ip: ! R 
4 ! t IOCB 1. 004 ! 
LOO -----2--6--2----------- WR DE 1 ! 
! ! 1 1—————- ! 
NEE 9-521 07 001 
J !: ! ! #1 ! 
fo -------- ! 1-————1 
1. EN E >! | <------ 
1. (e S | CHE E 
ek bo ! 1 
p---------------»5|1 #3 ` ! 
! D ! 


.IOCBPOINTER ^'^ 


Copyright (C) 1978 Software Dynamics 
x -226- 


SDOS USER'S MANUAL 


apos Tables 


IOCB i | IOCB . IOCB IOCB 
I DRIVE 1 I pU I 7 I 
1 DCB. d 4 I! `! SES ZE t og 
do. ! 1 tod ped EJ 
01 LSN 1 olg, fe Gef ps 1.4 "1 CHANNEL ` 
! y 1 SE ER rod ! BLOCKS 
---------- SS ------- 4 | d sf 
y b (b 101 1 ! eo! Le 
(d ! N Eod 1 `l Ee oh, ! 
LA pou wood ub stat og 1: 
1 1 » 1. 1 hu sal Eist en 
1 p deep cp 1 d ! 1 CP 
Lo] D roo dod ! 1 Ac 
Ge : 5 S ei E ate 
! e 1. 
1 1 
l 4 
! RDSI RDSI RDSI RDSI ! 
! 1 
1---»1 DRIVE | 1 1 1«-1 RESIDENT: 
| ! ! ! ! ! DISK SECTOR 
t LSN 1 ! ! ! INFO BLOCKS 
! ! ! ! ! RDSI:SIZE- 
! MODF ! ! ! ! BYTES ` 
1 ! ! ! L 
--------- ! 1 ! 21 
A ! | 1 ! ! 1 
[d ! ORDER 1 n E ! | 
! l wee ene »------ »------» ! ORDER-OF-READING CHAIN 
! 1 ! ! p 0001 ! 
! ES. VE ES E 
LI 
1---»51 dox ! 1 ! DISK SECTOR 
de ! f od tor ! BUFFERS 
! p tol ! BUFFERSIZE-MAX OF ALL DSKINFO: NBI 


"e ^RSDI blocks are chained together two ways for JERRY | 
x aeron delet Ion, : ; n 


25 Disk sector read dpdabes chain in LRU —-— 


Copyright. (C) 1978 Software Dynamics. 
BEER f 


SDOS USER'S MANUAL 


 SDOS BOOT SEQUENCE 


This information is only needed by those who are going to 
modify an old or build a new I/O package for SDOS, and^ 
concerns itself with the sequence of events that occurs (this 
sequence can be used to determine where breakpoints need to 
be inserted when debugging an 1/0 package). : 


-After a RESET to the. 6800 microprocessor, control is usually 
transferred to the system debugger. For many SDOS systems, 
this is IDB. With IDB, the bootstrap process is started by 
typing the letter "G" immediately after a reset, or jumping 
^to a system-dependent ROM entry point. Other. systems. Have. 
some. Scheme for. starting thes bootstrap program. 


The ROM bobt program's. only job is to read Ee Sector 
Number zero into memory (usually at location $100) and 
transfer control to the first byte (again, at location $100). 


LSN zero contains disk map algorithm information, and the 


SDOS boot program. In several systems, the SDOS boot program... 


is larger than the space allocated in LSN 0 for it; in this 
case, the rest of the boot program is stored in memory image 
(not SDOS load records!) in the remaining sectors of Logical 
Cluster Number zero. The first part of the SDOS boot reads 
the rest of the SDOS boot into memory at successively higher 
memory locations.  SDOS has been designed to reserve 
locations Ø to SlFFF for the SDOS boot program. 


The SDOS boot program's function is to load SDOS itself. 
: SDOS is stored on the disk in the file SDOS.SYS in SDOS load 
record format (not memory image). Normally, locating all the 
data sectors of a file is a formidable task, but SDOS.SYS 
must be allocated to the contiguous set of clusters starting 
with Logical Cluster Number 1. This means that the boot 
program, once it has determined the LSN of the first sector 
in LCN #1, can find the LSN of the next sector of the 
SDOS.SYS file by merely adding one to the LSN of the (BEEN EQUE 
sector. 


One of the records in an SDOS load format file is a 
start-address record. Once the SDOS boot has processed all 
the load records in the SDOS.SYS file, it transfers control 
to. SDOS at the specified start address. f E 


$bos has an initialization routine that sets up the hardware 
and software for operation under the system. This code is 
executed once at boot time, and then discarded. This routine 
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has code starting at $2000, and does not use any memory above 
$3FFF, so it fits entirely within the address space normally 
assigned to user programs. After SDOS has been initialized, 
the reset routine performs a normal user SYSCALL: EXIT, and 
normal system: operation Commences. e 


Here we describe the sequence of routines called that are 
-listed in the configuration (CNFG:xxx) tables in the I/O 
package. ; l : 


First, SDOS sets the.stack pointer to the value specified by 
CNFG:DRIVERBASE (the end of the user's address space). Next, 
the DRIVER:RESET routine of each non-disk device driver is 7 
called. “These routines are called in the order specified by- 


tbe CNFG:DEVICEDCBs list. Then the DRIVER:DISKRESET routines ` 


are called, with the DISKINFO table completely initialized 
(in particular, DISKINFO:NLSN has been calculated from. : 
-.DISKINFO:NSPT, :NTPC, :NCYL). These routines are called in- 
the order specified by the CNFG:DISKDCBs list. Finally, the 
disk buffer pool is initialized (no I/O package routines are 
needed for this!). Since DRIVER:RESET and DRIVER:DISKRESET 
are once-only routines, they usually are assembled into the 
disk buffer pool as the buffer pool is not initialized by. 
SDOS until after all the device reset routines have been 
called, and they are no longer needed. 


Next, SDOS counts the number of time-out blocks as specified 
by CNFG:TIMEOUTLIST. It then adds its timeout-task and the 
user task to end of the (CNFG: TASKQUEUE) list of tasks 
provided by the I/O package (so that the time-out and user 
tasks have lower priority than I/O package defined tasks). 
Finally, SDOS calls CNFG:INTSETUP to set up the interrupt ` 
system (all execution from boot up to and including this 
point is done with INTERRUPTS DISABLED!). 


Soon after the INTSETUP routine is executed, SDOS calls 
CNFG:INTENABLE and system operation is in full swing. 


Finally, the SDOS init routine displays a banner identifying 
the version of SDOS, reads the boot sector from the disk 
again: and displays the disk identification. Then SDOS init 
|. does à SYSCALL: pert, and the DEFAULTPROGRAM is dea: 

i 
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SDOS SYSTEM GENERATION 


SDOS System Generation (SYSGEN) is the process by which the 
SDOS system modules are configured, combined, and placed on a 
particular hardware configuration. ‘Typically, SYSGENs are 
performed to allow for new devices and/or. memory 


configurations, 


The ` ‘following programs/files are necessary to perform a SDOS 
SYSGEN. These programs/files are supplied only when 


specially E ER from SD. 


| lg SDOSSYSGEN. This program converts the SDOS system Delect 
. files and places them as necessary onto the SYSGENable disk. 


2. SDOSIOPACK.ASM*, This file contains the I/O drivers 
source to interface to the systems devices. It may be 
necessary to modify this package to allow for new devices or. 


f different menory configurations. 


: 3. SDOSIOPKDEFS. ASM*. This. file contains the SDOS 


definitions necessary to provide for Ge between the 
SDOSIOPACKAGE and the SDOSSYSTEM. . 


4. SDOSBOOT.MIK*. This file contains the disk bootstrap 


driver. 


5. SDOSSYSddK.MIK*. This file will contain the SDOS system 
object which has been assembled to reside in the size system 


^ Specified i "dd" (kilobytes). 


*Note: The filenames given above may not exactly match the . 
filenames as Provided. 


Using the programs described above and the standard SDOS 
programs (EDIT, COPY, ASM), the following procedure can be 
followed to perform a typical SDOS SYSGEN. 


l. If modifying or adding a device driver to SDOS, the 
SDOSIOPACK.ASM source file is modified via the editor (EDIT) 
and then appended to the SDOSIOPKDEFS.ASM file using the COPY 
command. . The resulting file is then assembled (ASM) with its 


¿origin (ORG) set at the proper location and the appropriate 
.. device Selection flags set. 
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. COPY SDOSIOPKDEFS. ASM,SDOSIOPACK.ASM TO JUNK 
. ASM 
Source File = JUNK <CR> 


2. If SYSGENing a SDOS- system with a new disk controller, 
"then a new bootstrap will be required. This can usually be 
constructed by modifying the existing SDOSBOOT.ASM ane. 
reassembling to form a new SDOSBOOT. MIK. 


3. A formatted disk should now be initialized with the 

A SDOSDISKINIT program. - This program is responsible for 
-_placing a initialized Directory and Map on the SYSGENable 
disk. For details and “Operating instructions, refer to 

..SDOSDISKINIT... l : EE 


A, Now the SDOSSYSGEN program Should be used to bise the 
 BOOT.SYS and SDOS.SYS files on the SYSGENable disk (see the 
SDOSSYSGEN description). l 


5. Now the default operator's program should be copied to 
the newly SYSGENed disk. After this is complete, the utility 
programs can be copied individually or by use of i 
SDOSDISKBACKUP program. | 


6. At this point, an SDOSDISKVALIDATE should be s m to 
check for any file errors. 
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'"SDOSSYSGEN 

- The SDOSSYSGEN program. is responsible for combining, 

_» converting, | and placing the SDOS system object files on an 
- initialized ust thereby producing a working SDOS system. 


The SDOSSYSGEN program is invoked by typing: 


.SDOSSYSGEN 


The program responds with. its banner, a listing of the 


—. Systems it can SYSGEN onto, which is determined by its 
Ogre rap offset. and the e 


ENTER THE DISK TO 'SYSGEN ON? 


_. The operator should reply with the drive specifier containing. 
"an initialized disk on which the SYSGEN is to take place. 


Typically this would be "D1:" but not necessarily. 


The program will now ask for the MIKBUG object files which- 


` will comprise the BOOT.SYS and SDOS.SYS files on the SYSGEN 
disk. 


The first file will be placed in BOOT.SYS and all the 
others will be merged in the order given to form SDOS.SYS. 
The proper order would appear as: 


ENTER FILENAME #1? SDOSBOOT.MIK 
ENTER FILENAME $2? SDOSIOPACK.MIK 
ENTER FILENAME #3? SDOSSYSddK.MIK 
ENTER FILENAME #4? SDOSPATCH.MIK 
ENTER FILENAME $5? - 


(A null filename terminates input.) 


Once all the files are entered, they are converted to the 


proper format, and at the same time, placed in BOOT.SYS or 
As each file is processed, its file number is. 


corrected and the SYSGEN program restarted. 


At completion, the program prints the SYSGEN is complete and 
“oes exits. 
+ DIRECTORY.SYS, DISKMAP.SYS, BADCLUSTERS.SYS. 
oc files. (including the DEFAULTPROGRAM and ERRORMSGS. BPP) need 
oe -be bc to the disk before it is ppo ARTS 


The newly SYSGENed disk has only the files BOOT.SYS, 
Other needed 
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—SDOS1.9: 
2€0: * 
261: * 
2€2: * 
265: FILESYSTEMVERSION 
264: ` I 
265: 
266: LIR:NAMESIZE 
267: IIR:FILENAME 
268: LIR:FCBDATA 
2€6S: LIR:HLCN 
270: LIR:HCSIC 
271: LIR:NCLUSTERS 
272: LIR:FILESIZE. 
2738: CIR: PROTECTICN 
274: DIR: DAY 
275: TIRsMONTH- 
276: LTIR: YEAR 
277: LIR: VERSION 
278: TIR:FCBDATASIZE 
27S: c 
ZER: TIR:ENTRYSIZE 
261: * 
282: * 
2EZ: * 
284: PROT::DELETE 
285: PROT: :WRITE 


DIRECTORY ENTRY DISPLACEMENTS 


EQU $10 - VERSION 1.0 OF FILESYSTEM FORMAT 

ORG 8 - s 

EQU 1€ LENGTH OF DIRECTORY NAME det fe 

RMB. DIR:NAMESIZE FILENAME IN ASCII 

RMB Ø FCB PATA FOR FILE MANAGEMENT STARTS HERE 
RMB LCN:SIZE LCN OF HEALER CLUSTER ` 

RMB 1 f HEADER CLUSTER INITIALIZED COUNT ; 

RMB LCN:SIZE NUMBER OF CLUSTERS ALLOCATED TO FILE. 

RMB 4 LOGICAL SIZE OF FILE IN BYTES 

RMB 1 PROTECTION BITS 

RMB 1 CREATION DATE OF FILE 

RMB 1 MONTE OF FILE CREATION 

RMB 1 YEAR OF FILE CREATION 

RMB 1 VERSION NUMBER OF FILE (2-255) 

ECU *-TIR:FCBDATA ` 4 BYTES REQUIRED TO MANAGE FILES IN FCBS 
RMB 32-* SPACE FOR SLOP 

FQU T 
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“LOG CHANNEL 


SYSCHANNEL 
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DISKMAP.: TISPLACEMENTS 
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RMB i 

EQU 8 # MAP BITS PER BYTE 

2727 | SM 

son Zu M USED AS DISPLACEMENT ON SECTOR BYTE FETCH 
Rous UE READ-AHEAD HAPPENS ONLY IF MORE BUFFERS. AV. 


HEATER CLUSTER DISPLACEMENTS 


-ORG £ 


RMB LCN:SIZE 


.WEIRD CHANNEL DEFINITIONS 


EQU SFE (LOG CHANNEL MUST BE LOWEST OF THESE) 
EQU ` $FE SYSTEM 1/0 CHANNEL (RESERVED) 
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